NAV
shell

Introduction

Documentation for CloudMQTT API.

Authentication

Authentication is done by sending your API key in the password field in Basic Auth, the username should be kept empty.

curl -u :apikey \
  https://api.cloudmqtt.com/api/user

Instance

Restart

curl -XPOST -u :apikey \
  https://api.cloudmqtt.com/api/instance/restart

HTTP Request

POST https://api.cloudmqtt.com/api/instance/restart

Reset

curl -XPOST -u :apikey \
  https://api.cloudmqtt.com/api/instance/reset

HTTP Request

POST https://api.cloudmqtt.com/api/instance/reset

Users

List users

curl -u :apikey \
  https://api.cloudmqtt.com/api/user

The above command returns JSON structured like this:

[
  {
    "username":"test"
  }
]

HTTP Request

GET https://api.cloudmqtt.com/api/user

Optional URL Query Parameters

Parameter Description
limit Limit number of records in result (max 1000)
page Page to fetch. 1-indexed.
query Filter result by matching start of usernames with query

Get user info

curl -u :apikey \
  https://api.cloudmqtt.com/api/user/test

The above command returns JSON structured like this:

{
  "username":"test",
  "acls": [{
    "topic":"sensor/%u",
    "read":false,
    "write":true
  }]
}

HTTP Request

GET https://api.cloudmqtt.com/api/user/<USERNAME>

URL Parameters

Parameter Description
USERNAME Username of the user to get info about

Create user

curl -u :apikey \
-d '{"username":"test", "password":"super_secret_password"}' \
-H "Content-Type:application/json" https://api.cloudmqtt.com/api/user

HTTP Request

POST https://api.cloudmqtt.com/api/user

Request Parameters

Parameter Description
username Username for the new user
password Password for the new user

Update user password

curl -XPUT -u :apikey \
-d '{"password":"super_secret_password"}' \
-H "Content-Type:application/json" https://api.cloudmqtt.com/api/user/test

HTTP Request

PUT https://api.cloudmqtt.com/api/user/<USERNAME>

URL Parameters

Parameter Description
USERNAME The user to update

Request Parameters

Parameter Description
password New password for the user

Delete user

curl -XDELETE -u :apikey \
https://api.cloudmqtt.com/api/user/test

HTTP Request

DELETE https://api.cloudmqtt.com/api/user/<USERNAME>

URL Parameters

Parameter Description
USERNAME The user to delete

ACL

List ACL rules

curl -u :apikey \
  https://api.cloudmqtt.com/api/acl

The above command returns JSON structured like this:

[
  {
    "type":"topic",
    "pattern":"test/users/topic",
    "read":true,
    "write":true,
    "username":"custom-user"
  },
  {
    "type":"pattern",
    "pattern":"sensor/%u/data",
    "read":true,
    "write":true,
    "username":null
  }
]

There are two types of ACL rules, topic and pattern. Topic ACLs is applied to a given user. Pattern ACLs is applied to all users.

Creating and deleting users and ACLs are asyncronous tasks and may take up to a minute. Poll list API to see when ready.

HTTP Request

GET https://api.cloudmqtt.com/api/acl

Create ACL Rule

curl -u :apikey \
-d '{"type": "topic", "username":"test", "pattern": "readonly", "read": true, "write": false}' \
-H "Content-Type:application/json" \
https://api.cloudmqtt.com/api/acl

HTTP Request

POST https://api.cloudmqtt.com/api/acl

Request Parameters

Parameter Description
type Which type of ACL rule to create
username Which user the rule applies to
pattern Pattern for which topics to match
read Allow reads
write Allow writes

Delete ACL Rule

curl -XDELETE -u :apikey \
-d '{"username":"test", "topic":"readonly"}'
-H "Content-Type:application/json" \
https://api.cloudmqtt.com/api/acl

HTTP Request

DELETE https://api.cloudmqtt.com/api/acl

Request Parameters

Parameter Description
username Delete rules for this user
topic Delete rules for this topic

Formats

All API end points support form FormData and JSON in the request. You need to format the request accordingly and if you send the request as JSON be sure to add the content type header Content-type: application/json otherwise the server won't be able to parse your request.

Status Codes

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The kitten requested is hidden for administrators only.
404 Not Found -- The specified kitten could not be found.
405 Method Not Allowed -- You tried to access a kitten with an invalid method.
429 Too Many Requests -- Rate limiting, you have requested too many kittens in a given amount of time.
500 Internal Server Error -- We had a problem with our server. Try again later.