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

Instance info🔗

Connections🔗

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

HTTP Request🔗

GET https://api.cloudmqtt.com/api/info/connections

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

# You can also pass the username in the body
curl -XPUT -u :apikey \
-d '{"username":"test","password":"super_secret_password"}' \
-H "content-type:application/json" https://api.cloudmqtt.com/api/user

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

# You can also pass the username in the body
curl -XDELETE -u :apikey \
-d username=foo \
https://api.cloudmqtt.com/api/user

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.

Use # for multi level wildcard acl.
Use + for single level wildcard acl.

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

Account🔗

Rotate password🔗

Initiate rotation of the user password on your instance.

curl -XPOST -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx \
  https://api.cloudmqtt.com/api/account/rotate-password

HTTP Request🔗

POST https://api.cloudmqtt.com/api/account/rotate-password

Rotate API key🔗

curl -XPOST -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx \
  https://api.cloudmqtt.com/api/account/rotate-apikey

HTTP Request🔗

POST https://api.cloudmqtt.com/api/account/rotate-apikey

Maintenance🔗

List, run and reschedule maintenance

List upcoming maintenance🔗

curl -XGET -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx https://api.cloudmqtt.com/api/maintenance

The above command returns JSON structured like this:

[
  {
    "id": 1234,
    "scheduled_by": "2022-02-05 00:36:00 +0000",
    "status": "scheduled",
    "required_by": "2022-03-05 00:00:00 +0000",
    "duration": "1 hour",
    "description": "..."
  }
]

HTTP Request🔗

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

Reschedule maintenance🔗

curl -XPUT -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
  -d '{"scheduled_by":"2022-02-05 00:36:00 +0000"}' \
  -H "Content-type: application/json" \
  https://api.cloudmqtt.com/api/maintenance/1234

HTTP Request🔗

PUT https://api.cloudmqtt.com/api/maintenance/<ID>

Request Parameters🔗

Parameter	Description
scheduled_by	Date string

URL Parameters🔗

Parameter	Description
ID	Maintenance id

Run maintenance now🔗

HTTP Request🔗

curl -XPOST -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx https://api.cloudmqtt.com/api/maintenance/<ID>

URL Parameters🔗

Parameter	Description
ID	Maintenance id

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🔗

Status Code	Meaning
200	The request completed successfully.
204	The request completed successfully.
400	Bad Request -- Your request might be 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.