Systemready API

The VAPIX® Systemready API makes it possible to find out, without authentication, if the Axis device is ready to handle external communication, configurations and video streaming on either the first or a consecutive boot up.

Overview

The API uses the systemready.cgi as its communication interface and supports the following methods:

Methods	Description
`systemready`	Query to check if the system is ready.
`getSupportedVersions`	Retrieve a list of supported API versions.

Identification

API Discovery: id=systemready
Firmware: 9.50 and later

Obsoletes

This CGI replaces polling of APIs such as getBrandInfo, which were used determine when the system was ready.

Common examples

How to use Systemready

This example will show you how to test if your device is ready to receive and handle requests.

1. Check if the system is ready with the following request:

http://<servername>/axis-cgi/systemready.cgi

JSON input parameters

{
  "apiVersion": "1.1",
  "context": "my context",
  "method": "systemready",
  "params": {
    "timeout": 20
  }
}

Please note that it will take up to 20 seconds before the system responds.

2. The response will appear if the system is or becomes ready during the timeout. If needsetup is yes the system is lacking an initial admin user, which must first be created using pwdgrp.cgi. It is not possible to call an API that requires authentication otherwise. An uptime field will show how many seconds the device has been active after it was booted. Finally, a previewmode, its duration given in seconds, will be included if the device is in preview mode.

Successful response

{
  "apiVersion": "1.1",
  "context": "my context",
  "method": "systemready",
  "data": {
    "systemready": "yes",
    "needsetup": "no",
    "uptime": "7800"
  }
}

Successful response with active preview mode

{
  "apiVersion": "1.1",
  "context": "my context",
  "method": "systemready",
  "data": {
    "systemready": "yes",
    "needsetup": "no",
    "uptime": "120",
    "previewmode": "7200"
  }
}

API specification

systemready

This method should be used to check if the system is ready for operation.

Request

Security level: Anonymous
Method: POST

http://<servername>/axis-cgi/systemready.cgi

Request body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": "<string>",
  "method": "systemready",
  "params": {
    "timeout": <timeout seconds>
  }
}

Parameter	Description
`apiVersion`	The API version that should be used.
`context`	The user sets this value and the application echoes it back in the response (optional).
`method`	The method that should be used.
`params`	Method specific parameters. Optional for some methods.
`timeout`	The maximum time `systemready.cgi` will take before returning a response. Valid responses are either `yes` or `no`.

Return value - Success

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": "<string>",
  "method": "systemready",
  "data": {
    "systemready": "yes/no",
    "needsetup": "yes/no",
    "uptime": "<seconds from when the device was started in seconds>",
    "previewmode": "<previewmode duration in seconds>"
  }
}

Parameter	Description
`apiVersion`	The API version that was used in the request.
`context`	The context set by the user in the request (optional).
`method`	The requested method.
`data`	Response specific data.
`systemready`	The system ready status. Accepted values are `yes` and `no`.
`needsetup`	Setup related parameter. If the returning value is `yes` an initial admin user must first be created using `pwdgrp.cgi`.
`uptime`	The device boot uptime, presented in seconds.
`previewmode`	Included when previewmode is enabled.

Return value - Failure

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>
  "method": "systemready",
  "error": {
    "code": <error code>,
    "message": "<error message>"
  }
}

Parameter	Description
`apiVersion`	The API version that was used in the request.
`context`	The context set by the user in the request (optional).
`method`	The requested method.
`error`	Error specific data.
`code`	The error code.
`message`	The error message for the corresponding error code.

getSupportedVersions

This method should be used when you want to retrieve a list containing all API versions supported by your device.

Request

Security level: Anonymous
Method: POST

http://<servername>/axis-cgi/systemready.cgi

Request body syntax

{
  "context": "<string>",
  "method": "getSupportedVersions"
}

Parameter	Description
`context`	The user sets this value and the application echoes it back in the response (optional).
`method`	The method that should be used.

Return value - Success

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "context": "<string>",
  "method": "getSupportedVersions",
  "data": {
    "apiVersions": ["1.0", "<Major>.<Minor>"]
  }
}

Parameter	Description
`context`	The context set by the user in the request (optional).
`method`	The requested method.
`data`	Response specific data.
`apiVersions`	A list containing all supported major versions along with their highest minor version, e.g. `["1.0", "1.2"]`.

Return value - Failure

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": "<string>",
  "method": "getSupportedVersions",
  "error": {
    "code": <error code>,
    "message": "<error message>"
  }
}

Parameter	Description
`apiVersion`	The API version that was used in the request.
`context`	The context set by the user in the request (optional).
`method`	The requested method.
`error`	The error specific data.
`code`	The error code.
`message`	The error message for the corresponding error code.

General error codes

The following table lists the general errors that can occur to any CGI method.

Code	Description
`1000`	Internal error. Refer to message field or logs.
`9000`	Internal error.