Mistake on this page? Email us

Connect API

Pelion Device Management Connect API allows web applications to communicate with devices. You can subscribe to device resources and read/write values to them. Device Management Connect allows connectivity to devices by queueing requests and caching resource values.
Version: 2
Host: https://api.us-east-1.mbedcloud.com

Endpoints

DeviceRequests

post /v2/device-requests/{device-id}
Send an async request to device Show more Show less

This API provides an interface to asynchronously call methods on a device.

The async-id is provided by the client, enabling the client to track the end-to-end flow with an identifier that is relevant to the end application. For example, a web application's session ID along with the device ID and the resource path could be used as the async-id. This also avoids any race conditions with the notification channel. All responses are sent through the currently configured notification channel as an AsyncIDResponse.

For GET methods, values may be fetched from an internal cache, instead of contacting the device.

See also /v2/endpoints/{device-id}/{resourcePath}.

Example URI:
POST /v2/device-requests/015f2fa34d310000000000010030036c?async-id=123e4567-e89b-12d3-a456-426655440000

Example payloads:
{ "method": "GET", "uri": "/5/0/1" }
{ "method": "PUT", "uri": "/5/0/1%20?k1=v1&k2=v2%22", "accept": "text/plain", "content-type": "text/plain", "payload-b64": "dmFsdWUxCg==" }

Immediate response:
202 Accepted

Example AsyncIDResponse, delivered via the notification channel:
{ "async-responses": [ { "id": "123e4567-e89b-12d3-a456-426655440000", "status": 200, "payload": "dmFsdWUxCg==", "ct": "text/plain", "max-age": 600 } ] }
Path parameters
device-id (required)
Path Parameter — The device ID generated by Device Management. format: uuid, 32 hexadecimal characters
Consumes
This API call consumes the following media types via the Content-Type request header:
  • application/json
Request body
body DeviceRequest (required)
Body Parameter — Device request to send.
Query parameters
async-id (required)
Query Parameter — The client-generated ID for matching the correct response delivered via a notification. format: 1-40 alphanumeric characters and dashes.
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
202 Accepted.
400 Bad request. Contains one of the errors RESOURCE_NOT_FOUND, DEVICE_NOT_CONNECTED, MALFORMED_JSON_CONTENT, MALFORMED_ASYNC_ID and TOO_MANY_REQUESTS String
401 Authentication failure.
404 Device not found. Contains error DEVICE_NOT_FOUND. String

Endpoints

get /v2/endpoints
(DEPRECATED) List registered endpoints. The number of returned endpoints is currently limited to 200. Show more Show less

Endpoints are physical devices having valid registration to Device Management. All devices regardless of registration status can be requested from Device Directory API '/v3/devices/`.

Note: This endpoint is deprecated and will be removed 1Q/18. You should use the Device Directory API /v3/devices/. To list only the registered devices, use filter /v3/devices/?filter=state%3Dregistered.

Example usage:

curl -X GET https://api.us-east-1.mbedcloud.com/v2/endpoints -H 'authorization: Bearer {api-key}'
Query parameters
type (optional)
Query Parameter — Filter endpoints by endpoint-type.
Return type
array[ Endpoint]
Example data
Content-Type: application/json
[ {
  "q" : false,
  "name" : "015f3850a657000000000001001002ab",
  "type" : "Light",
  "status" : "ACTIVE"
} ]
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Successful response with a list of endpoints (Array of endpoints). array[Endpoint]
get /v2/endpoints/{device-id}
List the resources on an endpoint Show more Show less

The list of resources is cached by Device Management Connect, so this call does not create a message to the device.

Example usage:

curl -X GET https://api.us-east-1.mbedcloud.com/v2/endpoints/{device-id} -H 'authorization: Bearer {api-key}'
Path parameters
device-id (required)
Path Parameter — A unique device ID for an endpoint. Note that the ID needs to be an exact match. You cannot use wildcards here.
Return type
array[ Resource]
Example data
Content-Type: application/json
[ {
  "obs" : true,
  "rt" : "light_sensor",
  "type" : "text/plain",
  "uri" : "/sen/light"
} ]
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Successful response with a list of resources (Array of resources). array[Resource]
404 Endpoint not found

Notifications

delete /v2/notification/pull
Delete notification Long Poll channel Show more Show less

To delete a notification Long Poll channel. This is required to change the channel from Long Poll to a callback. You should not make a GET /v2/notification/pull call for 2 minutes after channel was deleted, because it can implicitly recreate the pull channel. You can also have some random responses with payload or 410 GONE with "CHANNEL_DELETED" as a payload or 200/204 until the old channel is purged.

Example usage: curl -X DELETE https://api.us-east-1.mbedcloud.com/v2/notification/pull -H 'authorization: Bearer {api-key}'

Responses
status description schema
200 Success. The body can contain "REMOVED" if it was deleted by this call or "ALREADY_DELETED" if it was deleted before and not purged yet.
401 Unauthorized.
delete /v2/notification/callback
Delete callback URL Show more Show less

Deletes the callback URL.

Example usage:

curl -X DELETE https://api.us-east-1.mbedcloud.com/v2/notification/callback -H 'authorization: Bearer {api-key}'
Responses
status description schema
204 Successfully deleted.
401 Unauthorized.
403 Forbidden, the authorization token used is not an API key.
404 Callback URL does not exists.
get /v2/notification/callback
Check callback URL Show more Show less

Shows the current callback URL if it exists.

Example usage:

curl -X GET https://api.us-east-1.mbedcloud.com/v2/notification/callback -H 'authorization: Bearer {api-key}'
Return type
Example data
Content-Type: application/json
{
  "headers" : "{\"authorization\" : \"f4b93d6e-4652-4874-82e4-41a3ced0cd56\"}",
  "url" : "https://www.example.com/my-webhook"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 URL found. Webhook
401 Unauthorized.
403 Forbidden, the authorization token used is not an API key.
404 The callback URL does not exist.
get /v2/notification/pull
Get notifications using Long Poll Show more Show less

In this case, notifications are delivered through HTTP long poll requests. The HTTP request is kept open until an event notification or a batch of event notifications are delivered to the client or the request times out (response code 204). In both cases, the client should open a new polling connection after the previous one closes. Only a single long polling connection per API key can be ongoing at any given time. You must have a persistent connection (Connection keep-alive header in the request) to avoid excess TLS handshakes.

The pull channel is implicitly created by the first GET call to /v2/notification/pull. It is refreshed on each GET call. If the channel is not polled for a long time (10 minutes) - it expires and will be deleted. This means that no notifications will stay in the queue between polls. A channel can be also deleted explicitly by a DELETE call.

Note: If you cannot have a public facing callback URL, for example when developing on your local machine, you can use long polling to check for new messages. However, long polling is deprecated and will likely be replaced in future. It is meant only for experimentation and not for commercial usage. The proper method to receive notifications is a notification callback. There can only be one notification channel per API key at a time in Device Management Connect. If a callback notification channel already exists, you need to delete it before creating a long poll notification channel, and vice-versa.

Example usage:

curl -X GET https://api.us-east-1.mbedcloud.com/v2/notification/pull -H 'authorization: Bearer {api-key}'
Return type
Example data
Content-Type: application/json
{
  "registrations" : [ {
    "q" : false,
    "original-ep" : "my-device-123",
    "ept" : "Light",
    "resources" : [ {
      "path" : "/sen/light",
      "ct" : "text/plain",
      "obs" : true,
      "rt" : "light_sensor",
      "if" : "sensor"
    } ],
    "ep" : "015f3850a657000000000001001002ab"
  } ],
  "reg-updates" : [ "" ],
  "async-responses" : [ {
    "ct" : "text/plain",
    "payload" : "My4zMQ==",
    "max-age" : "60",
    "id" : "9e3c96b8-c4d7-496a-ab90-cc732b9b560e",
    "error" : "TIMEOUT",
    "status" : 200
  } ],
  "notifications" : [ {
    "path" : "/sen/light",
    "ct" : "text/plain",
    "payload" : "My4zMQ==",
    "max-age" : "60",
    "ep" : "015f3850a657000000000001001002ab"
  } ],
  "de-registrations" : [ "015f3850a657000000000001001002ab" ],
  "registrations-expired" : [ "015f3850a657000000000001001002ab" ]
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Success. NotificationMessage
204 No new notifications.
400 Callback notification channel already exists.
401 Unauthorized.
410 Pull channnel was deleted and waiting to be purged. This code is a result of incorrect client behavior (delete channel and then pull), which can prevent the creation of callback channel after the pull channel was deleted. The channel can be (randomly) recreated by this call when it was deleted and still not purged. This client behaviour can set the channel in an undefined state for some time. The channel may respond with 410 GONE or 200/204 codes randomly for some time. Finally, the channel will enter in a valid "channel exists" state.
put /v2/notification/callback
Register a callback URL Show more Show less

Register a URL to which the server should deliver notifications of the subscribed resource changes. To get notifications pushed, you also need to place the subscriptions. The maximum length of the URL, header keys and values, all combined, is 400 characters. Notifications are delivered as PUT messages to the HTTP server defined by the client with a subscription server message. The given URL should be accessible and respond to the PUT request with response code of 200 or 204. Device Management Connect tests the callback URL with an empty payload when the URL is registered. For more information on callback notification, see NotificationMessage.

Optional headers in a callback message:

You can set optional headers to a callback in a Webhook object. Device Management Connect will include the header and key pairs to the notification messages send them to callback URL. As the callback URL's are API key specific also the headers are.

One possible use for the additional headers is to check the origin of a PUT request and also distinguish the application (API key) to which the notification belongs to.

Note: Only one callback URL per an API key can be active. If you register a new URL while another one is already active, it replaces the active one. There can be only one notification channel at a time. If the Long Poll notification is already present, you need to delete it before setting the callback URL.

Expiration of a callback URL:

A callback can expire when Device Management cannot deliver a notification due to a connection timeout or an error response (4xx or 5xx). After each delivery failure, Device Management sets an exponential back off time and makes a retry attempt after that. The first retry delay is 1 second, then 2s, 4s, 8s, ..., 2min, 2min. The maximum retry delay is 2 minutes. The callback URL will be removed if all retries fail withing 24 hours. More about notification sending logic.

Supported callback URL protocols:

Currently, only HTTP and HTTPS protocols are supported.

HTTPS callback URLs:

When delivering a notification to an HTTPS based callback URL, Device Management Connect will present a valid client certificate to identify itself. The certificate is signed by a trusted certificate authorithy (GlobalSign) with a Common Name (CN) set to notifications.mbedcloud.com.

Example usage:

This example command shows how to set your callback URL and API key. It also sets an optional header authorization. When Device Management Connect calls your callback URL, the call contains the authorization header with the defined value.

curl -X PUT \
  https://api.us-east-1.mbedcloud.com/v2/notification/callback \
  -H 'authorization: Bearer {api-key}' \
  -H 'content-type: application/json' \
  -d '{
  "url": "{callback-url}",
  "headers": {"authorization" : "f4b93d6e-4652-4874-82e4-41a3ced0cd56"}
  }'
Consumes
This API call consumes the following media types via the Content-Type request header:
  • application/json
Request body
webhook Webhook (required)
Body Parameter — A json object that contains the optional headers and the URL to which the notifications need to be sent.
Responses
status description schema
204 Successfully subscribed.
400 Given URL is not accessible or the Long Polling channel already exists.
401 Unauthorized.
403 Forbidden, the authorization token used is not an API key.
415 Unsupported Media Type.

Resources

delete /v2/endpoints/{device-id}/{resourcePath}
Delete a resource path Show more Show less

A request to delete a resource path must be handled by both Device Management Client and Device Management Connect.

All resource APIs are asynchronous. These APIs respond only if the device is turned on and connected to Device Management Connect and there is an active notification channel.

Example usage:

curl -X DELETE \
  https://api.us-east-1.mbedcloud.com/v2/endpoints/{device-id}/{resourcePath} \
  -H 'authorization: Bearer {api-key}'
Path parameters
device-id (required)
Path Parameter — A unique Device Management device ID for the endpoint. Note that the ID must be an exact match. You cannot use wildcards here.
resourcePath (required)
Path Parameter — The URL of the resource.
Query parameters
noResp (optional)
Query Parameter

If you make a request with noResp=true, Device Management Connect makes a CoAP non-confirmable request to the device. Such requests are not guaranteed to arrive in the device, and you do not get back an async-response-id.

If calls with this parameter enabled succeed, they return with the status code 204 No Content. If the underlying protocol does not support non-confirmable requests, or if the endpoint is registered in queue mode, the response is status code 409 Conflict.

Return type
Example data
Content-Type: application/json
{
  "async-response-id" : "9e3c96b8-c4d7-496a-ab90-cc732b9b560e"
}
Responses
status description schema
202 Accepted. Returns an asynchronous response ID. AsyncID
400 Bad request.
404 Requested endpoint’s resource is not found.
409 Conflict. If noResp=true, the non-confirmable request is not supported by the used protocol.
410 Gone. Endpoint not found.
412 Precondition failed. Device responds with 4.12 CoAP response code. (Through AsyncIDResponse)
413 Request entity too large. (Through AsyncIDResponse)
415 Media type is not supported by the endpoint. (Through AsyncIDResponse)
429 Cannot make a request at the moment; the queue is full or queue was cleared because endpoint made full registration.
502 TCP or TLS connection to endpoint cannot be established.
503 Operation cannot be executed because endpoint is currently unavailable. (Through AsyncIDResponse)
504 Operation cannot be executed due to a time-out from the endpoint. (Through AsyncIDResponse)
post /v2/endpoints/{device-id}/{resourcePath}
Execute a function on a Resource or create new Object instance Show more Show less

With this API, you can execute a function on an existing resource and create new Object instance to the device. The resource-path does not have to exist - it can be created by the call. The maximum length of resource-path is 255 characters.

All resource APIs are asynchronous. These APIs respond only if the device is turned on and connected to Device Management Connect and there is an active notification channel.

Supported content types depend on the device and its resource. Device Management translates HTTP to equivalent CoAP content type.

Example usage:

This example resets the min and max values of the temperature sensor instance 0 by executing the Resource 5605 'Reset Min and Max Measured Values'.

curl -X POST \
  https://api.us-east-1.mbedcloud.com/v2/endpoints/{device-id}/3303/0/5605 \
  -H 'authorization: Bearer {api-key}'
Path parameters
device-id (required)
Path Parameter — A unique Device Management device ID for the endpoint. Note that the ID must be an exact match. You cannot use wildcards here.
resourcePath (required)
Path Parameter — The URL of the resource.
Consumes
This API call consumes the following media types via the Content-Type request header:
  • text/plain
  • application/xml
  • application/octet-stream
  • application/exi
  • application/json
  • application/link-format
  • application/senml+json
  • application/nanoservice-tlv
  • application/vnd.oma.lwm2m+text
  • application/vnd.oma.lwm2m+opaq
  • application/vnd.oma.lwm2m+tlv
  • application/vnd.oma.lwm2m+json
Request body
resourceFunction string (optional)
Body Parameter

This value is not needed. Most of the time resources do not accept a function but they have their own functions predefined. You can use this to trigger them.

If a function is included, the body of this request is passed as a char* to the function in Device Management Client.

Query parameters
noResp (optional)
Query Parameter

If you make a request with noResp=true, Device Management Connect makes a CoAP non-confirmable request to the device. Such requests are not guaranteed to arrive in the device, and you do not get back an async-response-id.

If calls with this parameter enabled succeed, they return with the status code 204 No Content. If the underlying protocol does not support non-confirmable requests, or if the endpoint is registered in queue mode, the response is status code 409 Conflict.

Return type
Example data
Content-Type: application/json
{
  "async-response-id" : "9e3c96b8-c4d7-496a-ab90-cc732b9b560e"
}
Responses
status description schema
202 Accepted. Returns an asynchronous response ID. AsyncID
400 Bad request.
404 Requested endpoint’s resource is not found.
409 Conflict. If noResp=true, the non-confirmable request is not supported by the used protocol.
410 Gone. Endpoint not found.
412 Precondition failed. Device responds with 4.12 CoAP response code. (Through AsyncIDResponse)
413 Request entity too large. (Through AsyncIDResponse)
415 Media type is not supported by the endpoint. (Through AsyncIDResponse)
429 Cannot make a request at the moment; the queue is full or queue was cleared because endpoint made full registration.
502 TCP or TLS connection to endpoint cannot be established.
503 Operation cannot be executed because endpoint is currently unavailable. (Through AsyncIDResponse)
504 Operation cannot be executed due to a time-out from the endpoint. (Through AsyncIDResponse)
get /v2/endpoints/{device-id}/{resourcePath}
Read from a resource Show more Show less

Requests the resource value either from the device or cache. If the value is not in the cache, the request goes all the way to the device. When the response is available, an AsyncIDResponse json object is received in the notification channel. The resource values can be also in cache based on max_age defined by the device side. The value found from the cache is returned immediately in the response.

The preferred way to get resource values is to use the subscribe and callback methods.

All resource APIs are asynchronous. These APIs only respond if the device is turned on and connected to Device Management.

See also how resource caching works.

Please refer to Lightweight Machine to Machine Technical specification for more inforamtion.

Example usage:

curl -X GET \
  https://api.us-east-1.mbedcloud.com/v2/endpoints/{device-id}/{resourcePath} \
  -H 'authorization: Bearer {api-key}'
Path parameters
device-id (required)
Path Parameter — Unique Device Management device ID for the endpoint. Note that the ID needs to be an exact match. You cannot use wildcards here.
resourcePath (required)
Path Parameter — The URL of the resource.
Query parameters
cacheOnly (optional)
Query Parameter — If true, the response comes only from the cache. Default: false. Device Management Connect caches the received resource values for the time of max_age defined in the client side.
noResp (optional)
Query Parameter

If a request is made with noResp=true, Device Management Connect makes a CoAP non-confirmable request to the device. Such requests are not guaranteed to arrive in the device, and you do not get back an async-response-id.

If calls with this parameter enabled succeed, they return with the status code 204 No Content. If the underlying protocol does not support non-confirmable requests, or if the endpoint is registered in queue mode, the response is status code 409 Conflict.

Responses
status description schema
200 Resource value found in cache. Returns the string value of the resource.
202 Accepted. Returns an asynchronous response ID. AsyncID
205 No cache available for resource.
400 Bad request.
404 Requested endpoint’s resource is not found.
409 Conflict. If noResp=true, the non-confirmable request is not supported by the used protocol.
410 Gone. Endpoint not found.
412 Precondition failed. Device responded with 4.12 CoAP response code. (Through AsyncIDResponse)
413 Request entity too large. (Through AsyncIDResponse)
415 Media type is not supported by the endpoint. (Through AsyncIDResponse)
429 Cannot make a request at the moment; the queue is full or queue was cleared because endpoint made full registration.
502 TCP or TLS connection to endpoint cannot be established.
503 Operation cannot be executed because endpoint is currently unavailable. (Through AsyncIDResponse)
504 Operation cannot be executed due to a time-out from the endpoint. (Through AsyncIDResponse)
put /v2/endpoints/{device-id}/{resourcePath}
Write to a Resource or use write-attributes (notification rules) for a Resource Show more Show less

With this API, you can write a new value to existing Resources or use the write attributes to set the notification rules for the Resources. The notification rules only work on the device client side and may not be supported by all clients.

This API can also be used to transfer files to the device. Device Management Connect LwM2M server implements the Option 1 from RFC7959. The maximum block size is 1024 bytes. The block size versus transferred file size is something to note in low quality networks. The customer application needs to know what type of file is transferred (for example txt) and the payload can be encrypted by the customer. The maximum size of payload is 1048576 bytes.

All resource APIs are asynchronous. These APIs respond only if the device is turned on and connected to Device Management Connect and there is an active notification channel.

Supported content types depend on the device and its resource. Device Management translates HTTP to equivalent CoAP content type.

Example usage:

This example sets the alarm on a buzzer. The command writes the Buzzer instance 0, "On/Off" boolean resource to '1'.

curl -X PUT \
  https://api.us-east-1.mbedcloud.com/v2/endpoints/{device-id}/3338/0/5850 -H "content-type: text/plain" \
  -H 'authorization: Bearer {api-key}' -d '1'
Path parameters
device-id (required)
Path Parameter — A unique Device Management device ID for the endpoint. Note that the ID must be an exact match. You cannot use wildcards here.
resourcePath (required)
Path Parameter — Resource URL.
Consumes
This API call consumes the following media types via the Content-Type request header:
  • text/plain
  • application/xml
  • application/octet-stream
  • application/exi
  • application/json
  • application/link-format
  • application/senml+json
  • application/nanoservice-tlv
  • application/vnd.oma.lwm2m+text
  • application/vnd.oma.lwm2m+opaq
  • application/vnd.oma.lwm2m+tlv
  • application/vnd.oma.lwm2m+json
Request body
resourceValue string (required)
Body Parameter — The value to be set to the resource.
Query parameters
noResp (optional)
Query Parameter

If you make a request with noResp=true, Device Management Connect makes a CoAP non-confirmable request to the device. Such requests are not guaranteed to arrive in the device, and you do not get back an async-response-id.

If calls with this parameter enabled succeed, they return with the status code 204 No Content. If the underlying protocol does not support non-confirmable requests, or if the endpoint is registered in queue mode, the response is status code 409 Conflict.

Return type
Example data
Content-Type: application/json
{
  "async-response-id" : "9e3c96b8-c4d7-496a-ab90-cc732b9b560e"
}
Responses
status description schema
202 Accepted. Returns an asynchronous response ID. AsyncID
400 Bad request.
409 Conflict. If noResp=true, the non-confirmable request is not supported by the used protocol.
410 Gone. Endpoint not found.
412 Precondition failed. Device responds with 4.12 CoAP response code. (Through AsyncIDResponse)
413 Request entity too large. (Through AsyncIDResponse)
415 Media type is not supported by the endpoint. (Through AsyncIDResponse)
429 Cannot make a request at the moment; the queue is full or queue was cleared because endpoint made full registration.
502 TCP or TLS connection to endpoint cannot be established.
503 Operation cannot be executed because endpoint is currently unavailable. (Through AsyncIDResponse)
504 Operation cannot be executed due to a time-out from the endpoint. (Through AsyncIDResponse)

Subscriptions

put /v2/subscriptions/{device-id}/{resourcePath}
Subscribe to a resource path Show more Show less

The Device Management Connect eventing model consists of observable resources.

This means that endpoints can deliver updated resource content, periodically or with a more sophisticated solution-dependent logic. The OMA LwM2M resource model including objects, object instances, resources and resource instances is also supported.

Applications can subscribe to objects, object instances or individual resources to make the device to provide value change notifications to Device Management Connect service. An application needs to call a /notification/callback method to get Device Management Connect to push notifications of the resource changes.

Notification rules

A web application can place dynamic observation rules for individual Object Instances and Resources to define when the device sends observations. More information in Notification rules.

All manual subscriptions are removed during a full device registration and applications need to re-subscribe at that point. To avoid this, you can use /subscriptions to set a pre-subscription.

Example usage:

curl -X PUT \
  https://api.us-east-1.mbedcloud.com/v2/subscriptions/{device-id}/{resourcePath} \
  -H 'authorization: Bearer {api-key}'
Path parameters
device-id (required)
Path Parameter — A unique Device Management device ID for the endpoint. Note that the ID must be an exact match. You cannot use wildcards here.
resourcePath (required)
Path Parameter — The URL of the resource.
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Successfully subscribed.
202 Accepted. Returns an asynchronous response ID that is used to reference the future asynchronous response. AsyncID
404 Endpoint or its resource not found.
412 Precondition failed. Cannot make a subscription for a non-observable resource. (Through AsyncIDResponse)
429 Cannot make a request at the moment; the queue is full or it was cleared because the endpoint made a full registration.
502 Subscription failed, endpoint not connected.
503 Subscription could not be established because the endpoint is currently unavailable. (Through AsyncIDResponse)
504 Subscription could not be established due to a time-out from the endpoint. (Through AsyncIDResponse)
get /v2/subscriptions/{device-id}/{resourcePath}
Read subscription status Show more Show less
Path parameters
device-id (required)
Path Parameter — A unique Device Management device ID for the endpoint. Note that the ID must be an exact match. You cannot use wildcards here.
resourcePath (required)
Path Parameter — The URL of the resource.
Responses
status description schema
200 Resource is subscribed.
404 Resource is not subscribed.
delete /v2/subscriptions/{device-id}
Delete subscriptions from an endpoint Show more Show less

Deletes all resource subscriptions in a single endpoint.

Example usage:

curl -X DELETE \
  https://api.us-east-1.mbedcloud.com/v2/subscriptions/{device-id} \
  -H 'authorization: Bearer {api-key}'
Path parameters
device-id (required)
Path Parameter — A unique Device Management device ID for the endpoint. Note that the ID must be an exact match. You cannot use wildcards here.
Responses
status description schema
204 Successfully removed.
delete /v2/subscriptions
Remove pre-subscriptions Show more Show less

Removes pre-subscriptions.

Example usage:

curl -X DELETE https://api.us-east-1.mbedcloud.com/v2/subscriptions -H 'authorization: Bearer {api-key}'
Responses
status description schema
204 Successfully removed subscriptions.
401 Unauthorized.
403 Forbidden, the authorization token used is not an API key.
delete /v2/subscriptions/{device-id}/{resourcePath}
Remove a subscription Show more Show less

To remove an existing subscription from a resource path.

Example usage:

curl -X DELETE \
  https://api.us-east-1.mbedcloud.com/v2/subscriptions/{device-id}/{resourcePath} \
  -H 'authorization: Bearer {api-key}'
Path parameters
device-id (required)
Path Parameter — A unique Device Management device ID for the endpoint. Note that the ID must be an exact match. You cannot use wildcards here.
resourcePath (required)
Path Parameter — The URL of the resource.
Responses
status description schema
204 Successfully removed subscription.
404 Endpoint or its resource not found.
get /v2/subscriptions/{device-id}
Read endpoints subscriptions Show more Show less

Lists all subscribed resources from a single endpoint.

Example usage:

curl -X GET \
  https://api.us-east-1.mbedcloud.com/v2/subscriptions/{device-id} \
  -H 'authorization: Bearer {api-key}'
Path parameters
device-id (required)
Path Parameter — A unique Device Management device ID for the endpoint. Note that ID must be an exact match. You cannot use wildcards here.
Return type
String
Example data
Content-Type:
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • text/uri-list
Responses
status description schema
200 List of subscribed resources. String
404 Endpoint not found or there are no subscriptions for that endpoint.
get /v2/subscriptions
Get pre-subscriptions Show more Show less

You can retrieve the pre-subscription data with the GET operation. The server returns with the same JSON structure as described above. If there are no pre-subscribed resources, it returns with an empty array.

Example usage:

curl -X GET https://api.us-east-1.mbedcloud.com/v2/subscriptions -H 'authorization: Bearer {api-key}'
Return type
Example data
Content-Type: application/json
""
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 OK. PresubscriptionArray
401 Unauthorized.
403 Forbidden, the authorization token used is not an API key.
put /v2/subscriptions
Set pre-subscriptions Show more Show less

Pre-subscription is a set of rules and patterns put by the application. When an endpoint registers and its ID, type and registered resources match the pre-subscription data, Device Management Connect sends subscription requests to the device automatically. The pattern may include the endpoint ID (optionally having an * character at the end), endpoint type, a list of resources or expressions with an * character at the end. Subscriptions based on pre-subscriptions are done when device registers or does register update. To remove the pre-subscription data, put an empty array as a rule.

Notification rules

A web application can place dynamic observation rules for individual Object Instances and Resources to define when the device sends observations. More information in Notification rules.

Limits:

  • The maximum length of the endpoint name and endpoint type is 64 characters.
  • The maximum length of the resource path is 128 characters.
  • You can listen to 256 separate resource paths.
  • The maximum number of pre-subscription entries is 1024.

Example request:

curl -X PUT \
  https://api.us-east-1.mbedcloud.com/v2/subscriptions \
  -H 'authorization: Bearer {api-key}' \
  -H 'content-type: application/json' \
  -d '[
         {
           "endpoint-name": "node-001",
           "resource-path": ["/dev"]
         },
         {
           "endpoint-type": "Light",
           "resource-path": ["/sen/*"]
         },
         {
           "endpoint-name": "node*"
         },
         {
           "endpoint-type": "Sensor"
         },
         {
           "resource-path": ["/dev/temp","/dev/hum"]
         }
      ]'
  • Subscribe to /dev resource of endpoint named node-001.
  • Subscribe to Light type of endpoints and their resources prefixed with /sen/.
  • Subscribe to all observable resources of endpoint names prefixed with node.
  • Subscribe to all observable resources of Sensor type endpoints.
  • Subscribe to /dev/temp and /dev/hum resources of all endpoints.

Note: For efficiency reasons, you should use resource path patterns in the pre-subscription data. This prevents the notification flow from unwanted resources.

Consumes
This API call consumes the following media types via the Content-Type request header:
  • application/json
Request body
presubsription PresubscriptionArray (required)
Body Parameter — Array of pre-subscriptions.
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • text/plain
Responses
status description schema
204 Successfully created.
400 Bad request, malformed content.
401 Unauthorized.
403 Forbidden, the authorization token used is not an API key.

Models

AsyncID

async-response-id (optional)
String Asynchronous response unique ID.

AsyncIDResponse

id (optional)
String The unique ID of the asynchronous response.
status (optional)
Integer The asynchronous response status code for a device operation related to a proxy request or manual subscription.
error (optional)
String An optional error message describing the error.
payload (optional)
String Requested data, base64 encoded.
ct (optional)
String The content type.
max-age (optional)
String Determines how long this value stays valid in the cache, in seconds. 0 means that the value is not stored in the cache.

DeviceRequest

method
String The CoAP request method. Allowed values are GET, POST, PUT and DELETE.
uri
String The URI path of the requested resource.
accept (optional)
String The content type of an accepted response.
content-type (optional)
String The content type of the payload.
payload-b64 (optional)
String The base64 encoded payload to be sent to the device.

Endpoint

name (optional)
String Unique Device Management Device ID representing the endpoint.
type (optional)
String Type of endpoint. (Free text)
status (optional)
String Deprecated and the value is always ACTIVE. Only used for API backwards compatibility reasons.
q (optional)
Boolean Determines whether the device is in queue mode.

Queue mode
When an endpoint is in queue mode, messages sent to the endpoint do not wake up the physical device. The messages are queued and delivered when the device wakes up and connects to Device Management Connect itself. You can also use the queue mode when the device is behind a NAT and cannot be reached directly by Device Management Connect.

EndpointData

ep (optional)
String Unique Device Management device ID.
original-ep (optional)
String In case of a self-provided endpoint name that is used to initiate the device registration, Device Management provides a new device ID to be used from that point on. The new Pelion platform provided Device ID is forwarded as the 'ep' property and the original self-provided one as the optional 'original-ep' property in a registration notification. The name and ID can then be mapped accordingly. Device Management saves the original endpoint name in the Device Directory for future device registrations so that you don't need to do the mapping again.
ept (optional)
String Endpoint type.
q (optional)
Boolean Queue mode (default value is false).
resources (optional)

NotificationData

ep (optional)
String Device Management Device ID.
path (optional)
String URI path.
ct (optional)
String Content type.
payload (optional)
String Base64 encoded payload.
max-age (optional)
String Max age value is an integer number of seconds between 0 and 2^32-1 but the actual maximum cache time is limited to 3 days. A default value of 60 seconds is assumed in the absence of the option.

NotificationMessage

notifications (optional)
registrations (optional)
reg-updates (optional)
de-registrations (optional)
registrations-expired (optional)
async-responses (optional)

Presubscription

endpoint-name (optional)
String The device ID.
endpoint-type (optional)
resource-path (optional)

PresubscriptionArray

Resource

uri
String The URL of the resource.
rt (optional)
String Application specific resource type that describes this resource. It is created by the client side application. Not meant to be a human-readable name for the resource. Multiple resource types may be included, they are separated by a space.
obs (optional)
Boolean Observable determines whether you can subscribe to changes for this resource. It can have values "true" or "false".
type (optional)
String The content type of the resource.

Important
You are encouraged to use the resource types listed in the LwM2M specification.

ResourcePath

A resource URI

ResourcesData

path (optional)
String Resource's URI path.
if (optional)
String Interface description that defines a name or URI that indicates how to interact with the target resource. It describes a generic interface type, such as a "sensor".
rt (optional)
String Application-specific resource type that describes this resource. It is created by the client side application. Not meant to be a human-readable name for the resource. Multiple resource types may be included, they are separated by a space.
ct (optional)
String Content type.
obs (optional)
Boolean Whether the resource is observable or not (true/false).

SubscriptionsList

A list of resource URIs, one per line

Webhook

url
String The URL to which the notifications are sent. We recommend that you serve this URL over HTTPS.
headers (optional)
map[String, String] The headers (key/value) sent with the notification. Optional.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.