MQTT client API
Description
The MQTT client API provides you with examples and specifications that makes it possible to directly control the MQTT (Message Queuing Telemetry Transport) messaging on your Axis device. This includes configuring the device to act as an MQTT client, which can then be connected to an MQTT broker to handle message exchanges.
For more information about MQTT brokers and how to connect them to Axis devices, see MQTT.
Model
The API implements client.cgi
as its communications interface and supports the following methods:
Method | Description |
configureClient | Configure the MQTT client. |
activateClient | Activate the MQTT client. |
deactivateClient | Deactivate the MQTT client. |
getClientStatus | Return the client status. |
getSupportedVersions | Retrieve API versions supported by the product. |
Identification
- API Discovery
id=mqtt-client
Common examples
MQTT client management
Use this example to exchange messages and data over MQTT. MQTT is based on two entities: the client and the broker. The client is able to send and receive messages, while the broker is responsible for routing said messages between different clients.
Configure the MQTT client
The first step to enable MQTT messaging is to configure the MQTT client, which includes all aspects such as the broker, security, protocol settings, last will testament, announcement, etc. To configure the client, a configureClient
request should be sent.
1. Configure the MQTT client.
http://<servername>/axis-cgi/mqtt/client.cgi
{
"apiVersion": "1.0",
"context": "some context",
"method": "configureClient",
"params": {
"server": {
"protocol": "ssl",
"host": "somebroker.somewhere.com",
"port": 8883
},
"username": "user_1",
"password": "password_1",
"keepExistingPassword": false,
"clientId": "unique_id_on_broker",
"keepAliveInterval": 20,
"connectTimeout": 30,
"cleanSession": true,
"autoReconnect": true,
"deviceTopicPrefix": "some/topic/prefix",
"lastWillTestament": {
"useDefault": false,
"topic": "Camera_1/ConnectionStatus",
"message": "Connection Lost",
"retain": true,
"qos": 1
},
"connectMessage": {
"useDefault": false,
"topic": "Camera_1/ConnectionStatus",
"message": "Connected",
"retain": true,
"qos": 1
},
"disconnectMessage": {
"useDefault": false,
"topic": "Camera_1/ConnectionStatus",
"message": "Disconnected",
"retain": true,
"qos": 1
},
"ssl": {
"validateServerCert": true
}
}
}
2. Parse the JSON response
{
"apiVersion": "1.0",
"context": "some context",
"method": "configureClient",
"data": {
}
}
{
"apiVersion": "1.0",
"context": "some context",
"method": "configureClient",
"error": {
"code": 1100,
"message": "Internal Error"
}
}
Activate the MQTT client
The client have two states: active and inactive. An active client is either trying to connect, or has already connected to a configured broker, while an inactive client does not have any effect, nor connection to the broker. To activate the client, an activateClient
request should be sent. Please note that an active client remains active even after a reboot.
1. Activate the MQTT client.
http://<servername>/axis-cgi/mqtt/client.cgi
{
"apiVersion": "1.0",
"context": "some context",
"method": "activateClient",
"params": {
}
}
2. Parse the JSON response.
{
"apiVersion": "1.0",
"context": "come context",
"method": "activateClient",
"data": {
}
}
{
"apiVersion": "1.0",
"context": "some context",
"method": "activateClient",
"error": {
"code": 1100,
"message": "Internal Error"
}
}
Deactivate the MQTT client
An activated MQTT can be turned off by sending a deactivation request, which will terminate the connection with the broker.
1. Deactivate the MQTT client instance.
http://<servername>/axis-cgi/mqtt/client.cgi
{
"apiVersion": "1.0",
"context": "some context",
"method": "deactivateClient",
"params": {
}
}
2. Parse the JSON response.
{
"apiVersion": "1.0",
"context": "some context",
"method": "deactivateClient",
"data": {
}
}
{
"apiVersion": "1.0",
"context": "somce context",
"method": "deactivateClient",
"error": {
"code": 1100,
"message": "Internal Error"
}
}
Get the MQTT client status
The status of an MQTT client can be obtained by making a status request, where the response will contain the status and configuration.
1. Request the status of the MQTT client.
http://<servername>/axis-cgi/mqtt/client.cgi
{
"apiVersion": "1.0",
"context": "some context",
"method": "getClientStatus",
"params": {
}
}
2. Parse the JSON response.
{
"apiVersion": "1.0",
"context": "some context",
"method": "getClientStatus",
"data": {
"status": {
"state": "inactive",
"connectionStatus": "disconnected"
},
"config": {
"server": {
"protocol": "ssl",
"host": "somebroker.somewhere.com",
"port": 8883
},
"username": "user_1",
"password": "*****",
"clientId": "unique_id_on_broker",
"keepAliveInterval": 20,
"connectTimeout": 30,
"cleanSession": true,
"autoReconnect": true,
"deviceTopicPrefix": "some/topic/prefix",
"lastWillTestament": {
"useDefault": false,
"topic": "Camera_1/ConnectionStatus",
"message": "Connection Lost",
"retain": true,
"qos": 1
},
"connectMessage": {
"useDefault": false,
"topic": "Camera_1/ConnectionStatus",
"message": "Connected",
"retain": true,
"qos": 1
},
"disconnectMessage": {
"useDefault": false,
"topic": "Camera_1/ConnectionStatus",
"message": "Disconnected",
"retain": true,
"qos": 1
},
"ssl": {
"validateServerCert": true
}
}
}
}
Get supported versions
Use this example to retrieve a list of API versions supported by your device.
1. Retrieve a list of supported API versions.
http://<servername>/axis-cgi/mqtt/client.cgi
{
"context": "some context",
"method": "getSupportedVersions"
}
2. Parse the JSON response.
{
"apiVersion": "1.0",
"context": "some context",
"method": "getSupportedVersions",
"data": {
"apiVersions": ["1.0"]
}
}
{
"apiVersion": "1.0",
"context": "some context",
"method": "getSupportedVersions",
"error": {
"code": 1100,
"message": "Internal error"
}
}
API specifications
configureClient
This API method is used when you want to configure the MQTT client.
Request
- Security level
Admin
- Method
POST
http://<servername>/axis-cgi/mqtt/client.cgi
{
"apiVersion": "<Major>.<Minor>",
"context": <string>,
"method": "configureClient",
"params": {
"server": {
"protocol": <string>,
"host": <string>,
"port": <integer>,
"basepath": <string>,
"alpnProtocol": <string>
},
"httpProxy": <string>,
"httpsProxy": <string>,
"username": <string>,
"password": <string>,
"keepExistingPassword": <boolean>
"clientId": <string>,
"keepAliveInterval": <int>,
"connectTimeout": <int>,
"cleanSession": <boolean>,
"autoReconnect": <boolean>,
"deviceTopicPrefix": <string>,
"lastWillTestament": {
"useDefault": <boolean>,
"topic": <string>,
"message": <string>,
"retain": <boolean>,
"qos": <int>
},
"connectMessage": {
"useDefault": <boolean>,
"topic": <string>,
"message": <string>,
"retain": <boolean>,
"qos": <int>
},
"disconnectMessage": {
"useDefault": <boolean>,
"topic": <string>,
"message": <string>,
"retain": <boolean>,
"qos": <int>
},
"ssl": {
"validateServerCert": <boolean>,
"clientCertID": <string>,
"CACertID": <string>
}
}
}
Return value - Success
- HTTP code
200 OK
- Content-type
application/json
{
"apiVersion":"<Major>.<Minor>",
"context": <string>,
"method": <string>,
"data": {
}
}
Parameter | Type | Description |
apiVersion | String | The API version that was used in the request. |
context | String | The context that was used when the request was made. |
method | String | The operation that was performed. |
data | Object | An empty object. |
Return value - Failure
- HTTP code
200 OK
- Content-type
application/json
{
"apiVersion": "<Major>.<Minor>",
"context": <string>,
"method": <string>,
"error": {
"code": <integer>,
"message": <string>
}
}
Parameter | Type | Description |
apiVersion | String | The API version that was used in the request. |
context | String | The context that was used when the request was made. |
method | String | The operation that was performed. |
error.code | Integer | The code representing the error that occurred in the request. |
error.message | Integer | Explains the error that occurred. |
Error codes
See for a complete list of potential error codes for this API.
Default LWT/Connected/Disconnected messages
LWT message
Topic | {device topic prefix}/event/connection |
Qos | 1 |
Retained | Yes |
Payload |
|
Connected message
Topic | {device topic prefix}/event/connection |
Qos | 1 |
Retained | Yes |
Payload |
|
Disconnected message
Topic | {device topic prefix}/event/connection |
Qos | 1 |
Retained | Yes |
Payload |
|
activateClient
This API method is used when you want to activate the MQTT client. Please note that this client will remain active after a reboot is not deactivated.
Request
- Security level
Admin
- Method
POST
http://<servername>/axis-cgi/mqtt/client.cgi
{
"apiVersion": "<Major>.<Minor>",
"context": <string>,
"method": "activateClient"
}
Parameter | Type | Description |
apiVersion | String | The API version that should be used in the request. |
context | String | The user sets this value and the application echoes it back in the response (optional). |
method | String | The operation that should be performed. |
Return value - Success
- HTTP code
200 OK
- Content-type
application/json
{
"apiVersion": "<Major>.<Minor>",
"context": <string>,
"method": <string>,
"data": {
}
}
Parameter | Type | Description |
apiVersion | String | The API version that was used in the request. |
context | String | The context that was used when the request was made. |
method | String | The operation that was performed. |
data | Object | An empty object. |
Return value - Failure
- HTTP code
200 OK
- Content-type
application/json
{
"apiVersion": "<Major>.<Minor>",
"context": <string>,
"method": <string>,
"error": {
"code": <integer>,
"message": <string>
}
}
Parameter | Type | Description |
apiVersion | String | The API version that was used in the request. |
context | String | The context that was used when the request was made. |
method | String | The operation that was performed. |
error.code | Integer | The code representing the error that occurred in the request. |
error.message | Integer | Explains the error that occurred. |
Error codes
See for a complete list of potential error codes for this API.
deactivateClient
This API method is used when you want to deactivate the MQTT client.
Request
- Security level
Admin
- Method
POST
http://<servername>/axis-cgi/mqtt/client.cgi
{
"apiVersion": "<Major>.<Minor>",
"context": <string>,
"method": "deactivateClient"
}
Parameter | Type | Description |
apiVersion | String | The API version that should be used in the request. |
context | String | The user sets this value and the application echoes it back in the response (optional). |
method | String | The operation that should be performed. |
Return value - Success
- HTTP code
200 OK
- Content-type
application/json
{
"apiVersion": "<Major>.<Minor>",
"context": <string>,
"method": <string>,
"data": {
}
}
Parameter | Type | Description |
apiVersion | String | The API version that was used in the request. |
context | String | The context that was used when the request was made. |
method | String | The operation that was performed. |
data | Object | An empty object. |
Return value - Failure
- HTTP code
200 OK
- Content-type
application/json
{
"apiVersion": "<Major>.<Minor>",
"context": <string>,
"method": <string>,
"error": {
"code": <integer>,
"message": <string>
}
}
Parameter | Type | Description |
apiVersion | String | The API version that was used in the request. |
context | String | The context that was used when the request was made. |
method | String | The operation that was performed. |
error.code | Integer | The code representing the error that occurred in the request. |
error.message | Integer | Explains the error that occurred. |
Error codes
See for a complete list of potential error codes for this API.
getClientStatus
This API method is used when you want to retrieve the status of the MQTT client.
Request
- Security level
Admin
- Method
POST
http://<servername>/axis-cgi/mqtt/client.cgi
{
"apiVersion": "<Major>.<Minor>",
"context": <string>,
"method": "getClientStatus"
}
Parameter | Type | Description |
apiVersion | String | The API version that should be used in the request. |
context | String | The user sets this value and the application echoes it back in the response (optional). |
method | String | The operation that should be performed. |
Return value - Success
- HTTP code
200 OK
- Content-type
application/json
{
"apiVersion": "<Major>.<Minor>",
"context": <string>,
"method": "getClientStatus",
"data": {
"status": {
"state": <string>,
"connectionStatus": <string>
},
"config": {
<all options used when configuring the client>
}
}
}
Return value - Failure
- HTTP code
200 OK
- Content-type
application/json
{
"apiVersion": "<Major>.<Minor>",
"context": <string>,
"method": <string>,
"error": {
"code": <integer>,
"message": <string>
}
}
Parameter | Type | Description |
apiVersion | String | The API version that was used in the request. |
context | String | The context that was used when the request was made. |
method | String | The operation that was performed. |
error.code | Integer | The code representing the error that occurred in the request. |
error.message | Integer | Explains the error that occurred. |
Error codes
See for a complete list of potential error codes for this API.
getSupportedVersions
This API method is used when you want to retrieve a list of supported API versions.
Request
- Security level
Admin
- Method
POST
http://<servername>/axis-cgi/mqtt/client.cgi
{
"context": <string>,
"method": "getSupportedVersions"
}
Parameter | Type | Description |
context | String | The user sets this value and the application echoes it back in the response (optional). |
method | String | The operation that should be performed. |
Return value - Success
- HTTP code
200 OK
- Content-type
application/json
{
"context": <string>,
"method": "getSupportedVersions",
"data": {
"apiVersions": ["<Major1>.<Minor1>","<Major2>.<Minor2>"]
}
}
Parameter | Type | Description |
context | String | The context that was used when the request was made (optional). |
method | String | The operation that was performed. |
data.apiVersions[]=<list of versions> | String | Specifies the list of supported versions and includes all major versions together with their highest supported minor version. |
<list of versions> | String | The list of ”<Major>.<Minor>” versions e.g. [“1.4”, “2.5”]. |
Return value - Failure
- HTTP code
200 OK
- Content-type
application/json
{
"apiVersion": "<Major>.<Minor>",
"context": <string>,
"method": <string>,
"error": {
"code": <integer>,
"message": <string>
}
}
Parameter | Type | Description |
apiVersion | String | The API version that was used in the request. |
context | String | The context that was used when the request was made. |
method | String | The operation that was performed. |
error.code | Integer | The code representing the error that occurred in the request. |
error.message | Integer | Explains the error that occurred. |
Error codes
See for a complete list of potential error codes for this API.
Error codes
The error codes for this API are sorted into the following ranges:
1100–1199
Generic errors that are common to many API:s and reserved for server errors, e.g. “Maximum number of configurations reached”. The cause can be seen in the server log and the problems can in some cases be solved by restarting the device.
1200–1999
API-specific server errors.
2100–2199
Generic error codes common to many API:s and reserved for client errors, e.g. “Invalid parameter”. These errors can be solved by changing the input data to the API.
2200–2999
API-specific client errors. Codes in this range may collide between different API:s.
Code | Description |
1100 | Internal error |
2100 | API version not supported |
2101 | Invalid JSON format |
2102 | Method not supported |
2103 | Required parameter missing or invalid |
2104 | Invalid parameter value specified |
2105 | Authorization failure |
2106 | Request size too large |