Application API

Description

Use VAPIX® Application API to upload, control and manage applications and their license keys.

Supported functionality:

Upload applications to the Axis product. See Upload application.
Start, stop, restart and remove applications. See Control application.
Configure settings usable by all applications. See Configure application.
Upload, install and remove license keys. See Manage license keys.
List installed applications. See List installed applications.

Identification

VAPIX® Application API is supported if:

Property: Properties.EmbeddedDevelopment.Version exists.

list.cgi requries:

Property: Properties.EmbeddedDevelopment.Version=1.20 and later.

Common examples

These examples demonstrate how to use the Application API. Text marked in bold should be replaced by application-specific values.

Upload an application to the Axis product.

Request:

POST /axis-cgi/applications/upload.cgi HTTP/1.1
Content-Type: multipart/form-data; boundary=fileboundary
Content-Length: <content-length>
 
fileboundary
Content-Disposition: form-data; name="packfil"; filename="ExampleApp.eap"
Content-Type: application/octet-stream
<application package data>

Upload a license key.

Request:

POST /axis-cgi/applications/license.cgi?action=uploadlicensekey&package=ExampleApp HTTP/1.1
Content-Type: multipart/form-data; boundary=fileboundary
Content-Length: <content-length>

fileboundary
Content-Disposition: form-data; name="licenseKey"; filename="ExampleAppLicenseKey.xml"
Content-Type: application/octet-stream
<license key data>

Allow an unsigned application to be installed.

http://<servername>/axis-cgi/applications/config.cgi?action=set&name=AllowUnsigned&value=true

Start the application.

Request:

http://myserver/axis-cgi/applications/control.cgi?action=start&package=ExampleApp

List installed applications.

Request:

http://myserver/axis-cgi/applications/list.cgi

Response:

<reply result="ok">
  <application Name="VideoMotionDetection" NiceName="AXIS Video Motion Detection"
      Vendor="Axis Communications" Version="2.1" ApplicationID="8546"
      License="None" Status="Running"
      ConfigurationPage="local/VideoMotionDetection/setup.shtml" />
  <application Name="CrossLineDetection" NiceName="AXIS Cross Line Detection"
      Vendor="Axis Communications" Version="1.1" ApplicationID="3051"
      License="Valid" Status="Stopped"
      ConfigurationPage="local/CrossLineDetection/setup.shtml" />
  <application Name="ExampleApp" NiceName="Example Application"
      Vendor="Example inc." Version="1.0" ApplicationID="1"
      License="Custom" Status="Stopped"
      ConfigurationPage="local/ExampleApp/settings.html"
      ValidationResult="http//validate.org/ExampleApp" />
</reply>

Upload application

The applications/upload.cgi is used to upload applications to the Axis product. Applications are installed automatically when uploaded.

Request

Access control: admin
Method: POST

Syntax:

http://<servername>/axis-cgi/applications/upload.cgi

Body:

POST http://<servername>/axis-cgi/applications/upload.cgi HTTP/1.1
Content-Type: multipart/form-data; boundary=fileboundary
Content-Length: <content-length>
  
fileboundary
Content-Disposition: form-data; name="packfil"; filename="application_name"
Content-Type: application/octet-stream
<application package data>

Response

Responses to applications/upload.cgi

Success:

HTTP Code: 200 OK
Content-Type: text/plain

Body:

OK

Error:

If the request failed, the following is returned.

HTTP Code: 200 OK
Content-Type: text/plain

Body:

Error: <error code>

Error code	Description
`1`	No valid package. The file type should be Embedded Axis Package (eap).
`2`	Verification failed. The verification of the package content failed. This can happen if the package version is not compatible with the product or due to architecture issues.
`3`	Package too large. The package file is too large or the disk is full.
`5`	Package not compatible. The package is not compatible with the Axis product. See the product logs for more information.
`10`	Unspecified error. See the product logs for more information.
`12`	Upload currently unavailable. A package upload is ongoing.
`13`	Installation failed. The package requires a user or group that is not allowed.

Control application

The applications/control.cgi is used to start, stop, restart and remove the application.

Request

Access control: admin
Method: POST

Syntax

http://<servername>/axis-cgi/applications/control.cgi?<argument>=<value>
[&<argument>=<value>...]

With the following argument and values:

Argument	Valid values	Description
`action=<string>`	`start` `stop` `restart` `remove`	`start` = Start the application. `stop` = Stop the application. `restart` = Restart the application. `remove` = Remove the application.
`package=<string>`	`<package name>`	The application to perform the action on.
`returnpage=<string>`	`<path to return page>`	Optional. The web page to return to after performing the action.

Response

Responses to applications/control.cgi

Success:

HTTP Code: 200 OK
Content-Type: text/plain

Body:

OK

Error:

If the request failed, the following is returned.

HTTP Code: 200 OK
Content-Type: text/plain

Body:

Error: <error code>

Error code	Description
`4`	Application not found. The specified application package could not be found.
`6`	The application is already running.
`7`	Application not running. The application must be running to perform the action.
`8`	Could not start application.
`9`	Too many applications are running. The application cannot be started.
`10`	Unspecified error. See the product logs for more information.

Configure application

The applications/config.cgi is used to access or configure settings that are usable by all applications, such as whether the device will allow both signed and unsigned applications to be installed.

Request

Access control: admin
Method: POST

Syntax

http://<servername>/axis-cgi/applications/config.cgi?action=<action>&name=<configname>&value=<configvalue>

With the following argument and values:

Argument	Valid values	Description
`action=<string>`	`set` `get`	`set` = Sets the value of a config parameter. `get` = Retrieves the value of a config parameter.
`name=<string>`	`AllowUnsigned`	The name of the config parameter that should be operated on. Valid values are described in the Configuration parameters table below.
`value=<string>` Optional	`true` `false`	Should be used when the action is set to specify the required value for the config parameter.

Configuration parameters

Configuration name	Type	Default value	Description
`AllowUnsigned`	Boolean	`true`	Controls whether unsigned applications can be installed. Can be either `true` or `false` (optional).

Response

Responses to applications/config.cgi

Success:

HTTP Code: 200 OK
Content-Type: text/xml

Body

<reply result="ok">
  <param name="configname" value="configvalue">
</reply>

Response example

<reply result="ok">
  <param name="AllowUnsigned" value="true"/>
</reply>

The response body contains a key and value corresponding to the param name="configname" in the request.

Parameter	Description
`param name=<key>`	The parameter name.
`value=<true \| false>`	The parameter value.

Error:

The following will be returned if the request failed.

HTTP Code: 200 OK
Content-Type: text/xml

Body

<reply result="error">
  ...
</reply>

Response example

<reply result="error">
<error type="32" message="An error occurred"/>
</reply>

Error code	Description
`1`	Internal error.
`32`	Unspecified error.

Schema for config.cgi response

<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="reply">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="param">
          <xs:complexType>
            <xs:simpleContent>
              <xs:extension base="xs:string">
                <xs:attribute type="xs:string" name="name"/>
                <xs:attribute type="xs:string" name="value"/>
              </xs:extension>
            </xs:simpleContent>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
      <xs:attribute type="xs:string" name="result"/>
    </xs:complexType>
  </xs:element>
</xs:schema>

Manage license keys

The applications/license.cgi is used to upload, install and remove license keys.

In order to receive the license key itself, the license key file must first be obtained from www.axis.com/applications. The client must then use action=uploadlicensekey to upload and install the license key.

note

To request a license key from www.axis.com/applications, a License Code and the Axis product’s serial number (S/N) are required.

Request

Access control: admin
Method: POST

Syntax

http://<servername>/axis-cgi/applications/license.cgi?<argument>=<value>
[&<argument>=<value>...]

With the following arguments and values.

Argument	Valid values	Description
`action=<string>`	`uploadlicensekey` `removelicensekey`	`uploadlicensekey` = Upload and install a license key. `removelicensekey` = Remove a license key.
`package=<string>`	`<package name>`	The name of the application to which the license key belongs.

Response

Responses to applications/license.cgi

Success:

HTTP Code: 200 OK
Content-Type: text/plain

Body:

OK

Error:

If the request failed, the following is returned.

HTTP Code: 200 OK
Content-Type: text/plain

Body:

Error: <error code>

Error code	Description
`21`	Invalid license key file.
`22`	File upload failed.
`23`	Failed to remove the license key file.
`24`	The application is not correctly installed.
`25`	The key’s application ID does not match the installed application.
`26`	The license key cannot be used with this version of the application.
`27`	Failed to connect to Axis online service.
`28`	Failed to receive license from Axis online service.
`29`	Bad configuration file for the application.
`30`	Wrong serial number.
`31`	The license key has expired.

List installed applications

The applications/list.cgi is used to list information about installed applications.

note

applications/list.cgi is supported for Properties.EmbeddedDevelopment.Version=1.20 and later.

Request

Access control: admin
Method: POST

Syntax

http://<servername>/axis-cgi/applications/list.cgi

This CGI has no arguments.

Response

Response to applications/list.cgi. The response is in XML format.

For the XML schema, see Schema for list.cgi response

HTTP Code: 200 OK
Content-Type: text/xml

Body:

<reply result="ok">
  <application Name="<Application Name>" NiceName="<Nice name>" Vendor="<Vendor name>"
      Version="<Version>" ApplicationID="<ID>" License="<License status>"
      LicenseExpirationDate="<Expiration date>" Status="<Application status>"
      ConfigurationPage="<Configuration link>" ValidationResult="<Validation URL>" />
  <application ... />
  ...
</reply>

Supported elements, attributes and values:

Element	Description	Attribute	Description
`application`	Information about one application	`Name`	Application short name.
		`NiceName`	Application official name.
		`Vendor`	Application vendor.
		`Version`	Application version.
		`ApplicationID`	Application ID
		`License`	License status: `Valid` = License is installed and valid. `Invalid` = License is installed but not valid. `Missing` = No license is installed. `Custom` = Custom license is used. License status cannot be retrieved. `None` = Application does not require any license.
		`LicenseExpirationDate`	Date (YYYY-MM-DD) when the license expires.
		`Status`	Application status: `Running` = Application is running. `Stopped` = Application is not running. `Idle` = Application is idle.
		`ConfigurationPage`	Relative URL to application configuration page.
		`ValidationResult`	Complete URL to a validation or result page.

Schema for list.cgi response

<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:simpleType name="EnumResult">
    <xs:restriction base="xs:string">
      <xs:enumeration value="ok" />
      <xs:enumeration value="error" />
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="StatusType">
    <xs:restriction base="xs:string">
      <xs:enumeration value="Running" />
      <xs:enumeration value="Stopped" />
      <xs:enumeration value="Idle" />
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="LicenseType">
    <xs:restriction base="xs:string">
      <xs:enumeration value="Valid" />
      <xs:enumeration value="Invalid" />
      <xs:enumeration value="Missing" />
      <xs:enumeration value="Custom" />
      <xs:enumeration value="None" />
    </xs:restriction>
  </xs:simpleType>

  <xs:complexType name="ErrorType">
    <xs:attribute name="type" type="xs:string" use="required" />
    <xs:attribute name="message" type="xs:string" use="required" />
    <xs:anyAttribute processContents="lax" />
  </xs:complexType>

  <xs:complexType name="ApplicationType">
    <xs:attribute name="Name" type="xs:string" use="required" />
    <xs:attribute name="NiceName" type="xs:string" />
    <xs:attribute name="Vendor" type="xs:string" />
    <xs:attribute name="Version" type="xs:string" />
    <xs:attribute name="ApplicationID" type="xs:integer" />
    <xs:attribute name="License" type="LicenseType" />
    <xs:attribute name="LicenseExpirationDate" type="xs:string" />
    <xs:attribute name="Status" type="StatusType" />
    <xs:attribute name="ConfigurationPage" type="xs:string" />
    <xs:attribute name="ValidationResult" type="xs:string" />
    <xs:anyAttribute processContents="lax" />
  </xs:complexType>

  <xs:element name="reply">
    <xs:complexType>
      <xs:choice>
        <xs:element name="application" type="ApplicationType" minOccurs="0" maxOccurs="unbounded" />
        <xs:element name="error" type="ErrorType" minOccurs="0" />
      </xs:choice>
      <xs:attribute name="result" type="EnumResult" />
    </xs:complexType>
  </xs:element>
</xs:schema>

Read general information

The applications/info.cgi is used to retrieve general information related to the applications currently running on your device.

Request

Access control: admin
Method: POST

Syntax:

http://<servername>/axis-cgi/applications/info.cgi

This CGI has no arguments.

Response

Responses to applications/info.cgi.

Success:

HTTP Code: 200 OK
Content-Type: text/xml

Body:

<reply result ="ok">
  <supportedSdks>
    <sdk>acap3</sdk>
    <sdk>acap4-native</sdk>
    <sdk>acap4-cv</sdk>
  </supportedSdks>
</reply>

Supported elements, attributes and values:

Argument	Description
`supportedSdks`	SDKs whose applications able to run on the device.
`sdk`	A specific SDK.

Error:

If the request failed, the following is returned.

HTTP Code: 200 OK
Content-Type: text/xml

Body:

<reply result="error">
  <error type="32" message=<"An error occurred"/>
</reply>

Error code	Description
`32`	Unspecified error.

Description​

Identification​

Common examples​

Upload application​

Request​

Response​

Control application​

Request​

Response​

Configure application​

Schema for config.cgi response​

Manage license keys​

Request​

Response​

List installed applications​

Request​

Response​

Schema for list.cgi response​

Read general information​

Description

Identification

Common examples

Upload application

Request

Response

Control application

Request

Response

Configure application

Schema for config.cgi response

Manage license keys

Request

Response

List installed applications

Request

Response

Schema for list.cgi response

Read general information