Edge storage API

Edge storage is the capability to record and store video on the edge, for example on a network share or an SD card. Recording on the edge can reduce the load on the network in particular in large installations and in installations with wireless connections.

The Edge storage API consists of:

Disk management API

List, format, mount and lock disks. A disk can be an SD card or a network share. See Disk management API.

Disk properties API

Set disk properties. See Disk properties API.

Network share API

Add, remove and manage network shares. See Network share API.

Recording storage Limit API

Control the amount of disk space a camera can use. See Recording storage limit API.

Recording API

Configure, start, access and play recordings. See Recording API.

Export recording API

Export a recording to a playable file. See Export recording API.

The Recording API is used to start and stop continuous recordings. Axis products also support event-triggered and scheduled recordings. These are configured using VAPIX® Event and action services, see Event and action services.

See also Edge storage events and actions.

Common examples

Using a network share

These examples demonstrate how to set up an Axis product to record continuously to a network share.

Add the network share “myshare” on the storage device “mynas”. User name for the share is “nasuser” and password is “pass”. The network share is given a user-friendly name “My Share”.

http://myserver/axis-cgi/disks/networkshare/add.cgi?schemaversion=1
&nicename=My%20Share&address=mynas&share=myshare&user=nasuser&pass=pass

The share’s unique Share ID is returned in the response. Here, the returned Share ID is 35419

Bind the network share to a disk. The disk is mounted automatically. The Share ID is from the add.cgi response above.

http://myserver/axis-cgi/disks/networkshare/bind.cgi?schemaversion=1
&shareid=35419

The Disk ID of the disk to which the share is bound is returned in the response. Here, the returned Disk ID is NetworkShare.

Define the cleanup policy for the network share by modifying parameters in the appropriate Storage group. First, use list.cgi to find the group number.

http://myserver/axis-cgi/disks/list.cgi?diskid=NetworkShare
Response:
HTTP/1.0 200 OK
Content-Type: text/xml
 
<?xml version="1.0" ?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation=
    "http://www.axis.com/vapix/http_cgi/disk/list1.xsd">
  <disks numberofdisks="1">
    <disk diskid="NetworkShare"
      name="My Share" 
      totalsize="4194304000"
      freesize="3355443200"
      cleanuplevel="95"
      cleanupmaxage="1"
      cleanuppolicy="none"
      locked="no"
      full="no"
      readonly="no"
      filesystem="cifs"
      status="OK"
      group="S1"
      requiredfilesystem="none"/>
  </disks>
</root>

As seen from the response, the disk to which the network share is bound is described by the parameters in the Storage.S1 group. Modify the parameters so that recordings are kept for 7 days.

http://myserver/axis-cgi/param.cgi?action=update
&Storage.S1.CleanupPolicyActive=fifo
&Storage.S1.CleanupMaxAge=7

Add a configuration for a continuous recording to the network share.

http://myserver/axis-cgi/record/continuous/addconfiguration.cgi?diskid=NetworkShare
&eventid=continuous_nas&options=resolution%3D640x480

Play the continuous recording from 2011–08–12T08:12:11Z to 2011–08–14T10:10:00Z. To make sure that all recorded material from this time period is played, also if the recording was interrupted, the recordings are first listed. The play request is then a loop over the found recordings.

First, list recordings with eventid=continuous_nas from the desired time period.

http://myserver/axis-cgi/record/list.cgi?listentity=recordingid
&eventid=continuous_nas
&starttime=2011-08-12T08:12:11Z
&stoptime=2011-08-14T10:10:00Z

The response below shows that the continuous recording was interrupted twice during the requested time period. A recording can for example be interrupted if the Axis product is restarted or if network connection is lost. The response contains information such as the Recording IDs, start and stop times of the three recordings found during the requested time period. Only a part of the response is shown here.

Response:
HTTP/1.0 200 OK
Content-Type: text/xml
   
<?xml version="1.0" ?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation=
    "http://www.axis.com/vapix/http_cgi/recording/list1.xsd">
  <recordings totalnumberofrecordings="6" numberofrecordings="3" >
    <recording diskid="NetworkShare"
      recordingid="20110812_081211_016F_00408C1834FD"
      starttime="2011-08-12T08:12:11Z" 
      stoptime="2011-08-13T09:30:30Z" ... > 
      <video ... />  
      <audio ... /> 
    </recording> 
    <recording diskid="NetworkShare"
      recordingid="20110813_093530_025B_00408C1834FD" 
      starttime="2011-08-13T09:35:30Z" 
      stoptime="2011-08-13T010:30:30Z" ... > 
      <video ... />  
      <audio ... /> 
    </recording> 
    <recording diskid="NetworkShare"
      recordingid="20110813_103530_037C_00408C1834FD" 
      starttime="2011-08-13T010:35:30Z" 
      stoptime="2011-08-14T10:10:00Z" ... > 
      <video ... /> 
      <audio ... /> 
    </recording> 
  </recordings> 
</root>

To play the recordings, use the Recording IDs, start times and stop times from the response. The start and stop times are returned in UTC combined date and time format and must be converted before being used in the RTSP Range header. For example, starttime="2011-08-12T08:12:11Z" should be converted to 20110812T081211Z. See Date and time format for more information.

The play request below is to be inserted in a loop over the recordings from the response; Rec.recordingid is replaced with each of the three returned Recording IDs and Rec.starttime and Rec.stoptime are replaced with the returned start and stop times (converted to the proper time format).

PLAY rtsp://myserver/axis-media/media.amp?recordingid=Rec.recordingid
Range: clock=Rec.starttime-Rec.stoptime

Using an SD card

These examples demonstrate how to use an SD card with an Axis product.

Set friendly name for storage 0 to “My SD card”.

http://myserver/axis-cgi/param.cgi?action=update
&Storage.S0.FriendlyName=My&20SD%20Card

List the file systems supported by the SD card.

http://myserver/axis-cgi/disks/getcapabilities.cgi?diskid=SD_DISK
Response:
HTTP/1.0 200 OK
Content-Type: text/xml
 
<?xml version="1.0" encoding="UTF-8"?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation=
    "http://www.axis.com/vapix/http_cgi/disk/capabilities1.xsd”>
  <disk diskid="SD_DISK" requiredfssupported="true">
    <filesystems>
      <filesystem name="vfat" nicename=" " requiredfssupported="false"/>
      <filesystem name="ext4" nicename=" " requiredfssupported="true"/>
    </filesystems>
  </disk>
</root>

Format the SD card with ext4.

http://myserver/axis-cgi/disks/format.cgi?diskid=SD_DISK&filesystem=ext4

The response gives the Job ID of the started job. Here, the returned Job ID is 4.

Check the progress of the format job with jobid=4.

http://myserver/axis-cgi/disks/job.cgi?jobid=4&diskid=SD_DISK

The response below shows that the format job is in progress, 15% of the job is done.

Response:
HTTP/1.0 200 OK
Content-Type: text/xml
 
<?xml version="1.0" ?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation=
    "http://www.axis.com/vapix/http_cgi/disk/checkjob1.xsd">
  <job jobid="4"
    diskid="SD_DISK"
    action="format"
    result="OK"
    progress="15"
</root>

By running job.cgi repeatedly, the progress of the job can be reported by showing incremental updates, for example:

15% 
32%
45%
68%
92%
Done!

Add a configuration for a continuous recording to the SD card.

http://myserver/axis-cgi/record/continuous/addconfiguration.cgi?diskid=SD_DISK
&options=resolution%3D640x480&eventid=continuous_0

Disk management API

Description

Disks are removable storage devices such as SD cards and network shares. The Disk management API is used to manage disks, for example to list, format, mount and lock disks.

Note
If using a network share, the share must first be added and bound to the disk using the Network Share API, see Network share API.

A disk is identified by its Disk ID. The Disk ID identifies a disk drive and not the physical disk, that is, the Disk ID does not change if the SD card or network share is replaced. For example, consider a network share with Disk ID NetworkShare. If the network share is unbound and replaced with a new one, the new share is also associated with the Disk ID NetworkShare.

The Disk management API consists of the following CGIs:

list.cgiRetrieve information about available disks. An available disk is mounted and ready to be used.
format.cgiFormat the disk. SD cards can be formatted with ext4 or vfat. Formatting a network share removes all recordings made by the Axis product performing the operation.
checkdisk.cgiCheck the status of a disk.
repair.cgiRepair the file system on a disk.
mount.cgiMount or unmount a disk. Mounting is done automatically when the system boots, when an SD card is inserted and when a network share is bound.
job.cgiCheck the progress of a format, check disk, repair, mount or unmount job. Typically used repeatedly until the job is done.
lock.cgiLock or unlock a disk. A locked disk cannot be formatted or written to. Ongoing recordings will be stopped if the disk is locked.
getcapabilities.cgiRetrieve the capabilities supported by the disk, for example the file systems the disk can be formatted with, if required file system is supported and if disk encryption is supported.
gethealth.cgiList the health status (wear level, temperature and overall health) of all disks.

The responses from format.cgi, checkdisk.cgi, repair.cgi and mount.cgi show if the job has been started or not. A successfully started job returns a Job ID, which should be used as input to job.cgi. Typically, job.cgi is run repeatedly until the job is finished. This workflow allows a user interface to be more responsive and to report the progress of a job by displaying incremental status updates, for example in a progress bar.

Prerequisites

Identification

Property

Properties.API.HTTP.Version=3

Property

Properties.LocalStorage.LocalStorage=yes

Property

Properties.LocalStorage.Version=1.00

Firmware

5.40 and later

Obsoletes

Parameter CleanupLevel is obsolete in firmware 5.50 and later. The parameter is replaced by an internal, fixed value.

Common examples

Set friendly name for storage 0 to “My SD Card”.

http://myserver/axis-cgi/param.cgi?action=update
&Storage.S0.FriendlyName=My&20SD%20Card

Get a list of all disks.

http://myserver/axis-cgi/disks/list.cgi?diskid=all

The response displays information about the disks.

Response:
HTTP/1.0 200 OK
Content-Type: text/xml
 
<?xml version="1.0" ?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation=
    "http://www.axis.com/vapix/http_cgi/disk/list1.xsd">
  <disks numberofdisks="2">
    <disk diskid="SD_DISK"
      name="My SD Card" 
      totalsize="2097152"
      freesize="2097152"
      cleanuplevel="95"
      cleanupmaxage="1"
      cleanuppolicy="none"
      locked="no"
      full="no"
      readonly="no"
      filesystem="vfat"
      status="OK"
      group="S0"
      requiredfilesystem="none"
      diskencryptionenabled="false"
      diskencrypted="false"/>
    <disk diskid="NetworkShare"
      name="My Share" 
      totalsize="4194304000"
      freesize="3670016000"
      cleanuplevel="95"
      cleanupmaxage="1"
      cleanuppolicy="none"
      locked="no"
      full="no"
      readonly="no"
      filesystem="cifs"
      status="OK"
      group="S1"
      requiredfilesystem="none"
      diskencryptionenabled="false"
      diskencrypted="false"/>
  </disks>
</root>

Unmount a network share.

http://myserver/axis-cgi/disks/mount.cgi?action=unmount&diskid=NetworkShare

The response gives the Job ID of the started job. Here, the returned Job ID is 3.

List the file systems supported by the SD card.

http://myserver/axis-cgi/disks/getcapabilities.cgi?diskid=SD_DISK
Response:
HTTP/1.0 200 OK
Content-Type: text/xml
 
<?xml version="1.0" encoding="UTF-8"?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation=
    "http://www.axis.com/vapix/http_cgi/disk/capabilities1.xsd”>
  <disk diskid="SD_DISK" requiredfssupported="true" encryptionsupported="true">
    <filesystems>
      <filesystem name="vfat" nicename=" " requiredfssupported="false"/>
      <filesystem name="ext4" nicename=" " requiredfssupported="true"/>
    </filesystems>
  </disk>
</root>

Format the SD card with ext4.

http://myserver/axis-cgi/disks/format.cgi?diskid=SD_DISK&filesystem=ext4

The response gives the Job ID of the started job. Here, the returned Job ID is 4.

Check the progress of the format job with jobid=4.

http://myserver/axis-cgi/disks/job.cgi?jobid=4&diskid=SD_DISK

The response below shows that the format job is in progress, 15% of the job is done.

Response:
HTTP/1.0 200 OK
Content-Type: text/xml
 
<?xml version="1.0" ?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation=
    "http://www.axis.com/vapix/http_cgi/disk/checkjob1.xsd">
  <job jobid="4"
    diskid="SD_DISK"
    action="format"
    result="OK"
    progress="15"
</root>

By running job.cgi repeatedly, the progress of the job can be reported by showing incremental updates, for example:

15% 
32%
45%
68%
92%
Done!

Get the wear level for all disks.

Request
http://<servername>/axis-cgi/disks/gethealth.cgi
Response
<?xml version="1.0" encoding="UTF-8"?>
<HealthStatusResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/disk/gethealth1.xsd">
  <HealthStatusSuccess>
    <HealthStatus diskid="SD_DISK" wear="25"/>
    <HealthStatus diskid="NetworkShare" wear="-1"/>
    <HealthStatus diskid="HDD_DISK" wear="13" temperature="315" overallhealth="1"/>
  </HealthStatusSuccess>
</HealthStatusResponse>

Parameters

Storage properties parameters

The parameters in the Properties.LocalStorage group identify the storage capabilities supported by the Axis product.

Properties.LocalStorage
ParameterDefault valueValid valuesAccess controlDescription
LocalStorageProduct dependentyes
no
admin: read
operator: read
viewer: read
yes = Storage is supported.
no = Storage is not supported.
VersionFirmware dependentIntegeradmin: read
operator: read
viewer: read
Specifies the version of the Disk Management API.
SDCardProduct dependentyes
no
admin: read
operator: read
viewer: read
yes = SD cards are supported.
no = SD cards are not supported.
ContinuousRecordingProduct dependentyes
no
admin: read
operator: read
viewer: read
yes = The product supports continuous recording profiles. Use record/continuous/addconfiguration.cgi to add a continuous recording configuration.
no = The product does not support continuous recording profiles. Use record/record.cgi to start a continuous recording.
NbrOfContinuousRecordingProfilesProduct dependentIntegeradmin: read
operator: read
viewer: read
Specifies the number of continuous recording profiles.

Mount directory parameters

Storage
ParameterDefault valueValid valuesAccess controlDescription
MountDir/var/spool/storage/var/spool/storageadmin: read
operator: read
Mount directory. Read-only.

Storage parameters

The parameters in the Storage group are used for disk management.

Storage.S#
ParameterDefault valueValid valuesAccess controlDescription
DiskIDStorage dependentStringadmin: read
operator: read
The Disk ID. Read only.
FriendlyNameStringadmin: read, write
operator: read, write
A user friendly name for the disk. This name can for example be displayed on a web page.
DeviceNodeStorage dependentStringadmin: read, write
operator: read
Valid values depends on what kind of storage that is used.
CleanupLevel950...99admin: read, write
operator: read
Obsolete in firmware 5.50 and later.

Cleanup level in percent of the total disk space. The oldest parts of unlocked recordings will be deleted when the used disk space (in percent of total disk space) exceeds the cleanup level.
Used in combination with CleanupPolicyActive=fifo.
CleanupMaxAge10...7000admin: read, write
operator: read
Maximum number of days that unlocked recordings are kept on the disk. Recording parts that are older than the specified number of days will be deleted.
Used in combination with CleanupPolicyActive=fifo.
Note: Recordings will be deleted earlier if the disk becomes full.
CleanupPolicyActivefifofifo
none
admin: read, write
operator: read
fifo = (first in, first out) Recordings are automatically deleted according to the rules specified by CleanupMaxAge.
none = Recordings must be deleted manually. No recordings are deleted by the system.
FileSystemStorage dependentext4
vfat
cifs
admin: read, write
operator: read
Current file system on the storage device. Valid values are storage dependent. Read only.
Lockednoyes
no
admin: read, write
operator: read
yes = The disk is locked and cannot be written to.
no = The disk is unlocked.
MountOnBootyesyes
no
admin: read, write
operator: read
yes = The disk is mounted on boot.
no = The disk is not mounted on boot. A manual mount is required.
RequiredFileSystemnonenone
ext4
admin: read, write
operator: read
none = Required file system is disabled.
ext4 = Required file system is set to ext4.
Note: To check if required file system is supported by the disk, use getcapabilities.cgi.
AutoRepairyesyes
no
admin: read, write
operator: read
yes= The file system is checked for errors before mounting and will be repaired if it is required. No check will be performed if the disk is locked.
no= The file system is not checked.
MountPointPermissions0770Stringadmin: read, write
operator: read, write
The file permissions, which are used to set the mount point, in the form of a string. This has only an effect on volumes with an ext4 file system.
Enabledyesyes
no
admin: read, write
operator: read
yes = The disk is enabled.
no = The disk is disabled, which means that it can’t be used, e.g. mounted.
You must restart your device after changing this parameter before the change can begin to take effect.
Note
The # is replaced by a group number, for example Storage.S0. The group number is an integer between 0 and N, where N is the number of disks supported by the Axis product.

List disks

Use disks/list.cgi to retrieve information about available disks and their status. An available disk is mounted and ready to be used.

Request

Access control

admin, operator

Method

GET

Syntax:
http://<servername>/axis-cgi/disks/list.cgi?<argument>=<value>
[&<argument>=<value>...]

With the following arguments and values:

ArgumentValid valuesDescription
diskid=<string>all
<Disk ID 1>, <Disk ID 2>, ...
Specify the Disk IDs of the disks to retrieve information about.
all= List all disks.
<Disk ID 1>, <Disk ID 2> = List the disks with the specified Disk IDs.

Response

Responses from disks/list.cgi

Success:

HTTP code

200 OK

Content-type

text/xml

Body:
<?xml version="1.0" ?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation=
    "http://www.axis.com/vapix/http_cgi/disk/list1.xsd">
  <disks numberofdisks="[number of disks returned in xml]">
    <disk diskid="[storage parameter DiskID]"
      name="[storage parameter FriendlyName]" 
      totalsize="[total size of storage in kB]"
      freesize="[free space of storage in kB]"
      cleanuplevel="[storage parameter CleanupLevel]"
      cleanupmaxage="[storage parameter CleanupMaxAge]"
      cleanuppolicy="[storage parameter CleanupPolicyActive]"
      locked="[storage parameter Locked]"
      full="[storage full]"
      readonly="[storage read only]"
      filesystem="[file system of storage]"
      status="[disk status]"
      group="[storage group]"
      requiredfilesystem="[required file system]"
      diskencryptionenabled="[true|false]"
      diskencrypted="[true|false]"/>
  </disks>
</root>
Note
In the disks/list.cgi response, some elements contain yes/no and some contain true/false.

Supported elements, attributes and values:

ElementDescriptionAttributeDescription
disksThe available disksnumberofdisksNumber of disks in the response.
diskInformation about the diskdiskidThe Disk ID.
nameUser-friendly disk name.
totalsizeTotal disk size in kilobytes (kB).
freesizeFree disk size in kilobytes (kB).
cleanuplevelObsolete in firmware 5.50 and later. Cleanup level in percent of total disk space.
cleanupmaxage

Maximum number of days that unlocked recordings are kept on the disk. Recording parts that are older than the specified number of days will be deleted.

Note: Recordings will be deleted earlier if the disk becomes full.

cleanuppolicy

fifo = (first in, first out). Recordings are automatically deleted after the number of days specified by cleanupmaxage.

none = Recordings are not deleted automatically. Must be deleted manually.

lockedThe disk is locked or unlocked.
yes = Disk is locked.
no = Disk is unlocked.
fullThe disk is full or not.
yes = Disk is full.
no = Disk is not full.
readonlyThe disk is read-only or not.
yes = Disk is read-only.
no = Disk is writable.
filesystemValue of parameter FileSystem.
status

Disk status. Possible values are:

disconnected = The disk is disconnected.

connected = The disk is connected but not mounted.

OK = The disk is working correctly.

failed = A problem has been discovered. Use checkdisk.cgi to find the problem.

no passphrase = Encryption is disabled but the disk is encrypted. Format the disk before use.

wrong passphrase = The disk is encrypted but the entered passphrase does not match the set passphrase. Set the correct passphrase before use.

not encrypted = Encryption is enabled. The disk is not encrypted and not mounted. Format and mount the disk before use.

groupThe parameter group Storage.S# defining the disk.
requiredfilesystem

The file system set as required file system. To change required file system, use disks/properties/setrequiredfs.cgi.

none = Required file system is not set.

diskencryptionenabled

true = Disk encryption is enabled.

false = Disk encryption is disabled.

diskencrypted

true = The disk content is encrypted. Disk content is encrypted when disk encryption is enabled and the disk has been mounted and formatted.

false = The disk content is not encrypted. Disk content is not encrypted when disk encryption is disabled, or when disk encryption is enabled but the disk has not yet been mounted and formatted.

Format disk

Use disks/format.cgi format disks. Disks are normally preformatted but can be reformatted with a different file system.

Important
Any data present on the disk is lost when the disk is formatted.

The response shows if the job has been started or not. A successfully started job returns a Job ID, which should be used as input to job.cgi, see Job progress.

SD cards can be formatted with ext4 or vfat. Using ext4 is recommended to reduce the risk of data loss if the card is ejected and after abrupt power cycling. To read SD cards formatted with ext4 on Windows, additional software is needed.

To format a network share, set the argument filesystem to cifs. Formatting a network share removes all data recorded to the share by the Axis product performing the operation. Data uploaded to a network share recipient and recordings made by other Axis products are not removed.

Use getcapabilities.cgi to retrieve the file systems that the disk can be formatted with.

If required file system has been set, the disk is formatted automatically when mounted. See Set required file system.

If disk encryption is enabled, the disk is encrypted when formatted. See Enable disk encryption.

Request

Access control

admin

Method

GET

Syntax:
http://<servername>/axis-cgi/disks/format.cgi?<argument>=<value>
[&<argument>=<value>...]

With the following arguments and values:

ArgumentValid valuesDescription
diskid=<string><Disk ID>Required.
Specify the Disk ID of the disk to format.
filesystem=<string>ext4
vfat
cifs
Specify the file system to format the disk with.
Available values depend on the disk and can be retrieved using disks/getcapabilities.cgi
Default: The file system present on the disk.

Response

Responses from disks/format.cgi

Success:

HTTP code

200 OK

Content-type

text/xml

Body:
<?xml version="1.0" ?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation=
    "http://www.axis.com/vapix/http_cgi/disk/startjob1.xsd">
  <job action="format"
    diskid="[Disk ID]"
    result="OK"
    jobid="[ID of the started job]"/>
</root>

Error:

HTTP code

200 OK

Content-type

text/xml

Body:
<?xml version="1.0" ?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation=
    "http://www.axis.com/vapix/http_cgi/disk/startjob1.xsd">
  <job action="format"
    diskid="[Disk ID]"
    result="ERROR"
    description="[error description]"/>
</root>

Supported elements, attributes and values:

ElementDescriptionAttributeDescription
jobInformation about the jobaction="format"The requested action: format
diskidThe Disk ID.
resultResult of the request.
OK = The format job was started successfully.
ERROR = The format job could not be started.
jobidJob ID.
descriptionError description.

Check disk

Use disks/checkdisk.cgi to check the integrity of the file system. If an error is found, try using repair.cgi to repair the file system.

The response shows if the job has been started or not. A successfully started job returns a Job ID, which should be used as input to job.cgi, see Job progress.

Note
Only SD cards formatted with ext4 can be checked using this CGI.

The request fails if the disk is mounted or if disk encryption is enabled without a valid passphrase.

Request

Access control

admin, operator

Method

GET

Syntax:
http://<servername>/axis-cgi/disks/checkdisk.cgi?<argument>=<value>
[&<argument>=<value>...]

With the following arguments and values:

ArgumentValid valuesDescription
diskid=<string><Disk ID>Required. The Disk ID of the disk to be checked.

Response

Responses from disks/checkdisk.cgi

Success:

HTTP code

200 OK

Content-type

text/xml

Body:
<?xml version="1.0" ?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation=
    "http://www.axis.com/vapix/http_cgi/disk/startjob1.xsd">
  <job action="checkdisk"
    diskid="[Disk ID]"
    result="OK"
    jobid="[ID of the started job]"/>
</root>

Error:

HTTP code

200 OK

Content-type

text/xml

Body:
<?xml version="1.0" ?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation=
    "http://www.axis.com/vapix/http_cgi/disk/startjob1.xsd">
  <job action="checkdisk"
    diskid="[Disk ID]"
    result="ERROR"
    description="[error description]"/>
</root>

Supported elements, attributes and values:

ElementDescriptionAttributeDescription
jobInformation about the job.action="checkdisk"The requested action: check disk
diskidThe Disk ID.
resultResult of the request.
OK = The check disk job was started successfully.
ERROR = The disk could not be checked.
jobidThe Job ID.
descriptionError description.

Repair disk

Use disks/repair.cgi to perform a file system repair on the selected disk.

Important
Repairing a disk may result in lost data.

The response shows if the job has been started or not. A successfully started job returns a Job ID, which should be used as input to job.cgi, see Job progress.

Note
Only SD cards formatted with ext4 can be repaired using this CGI.

The request fails if the disk is mounted or if disk encryption is enabled without a valid passphrase.

Request

Access control

admin

Method

GET

Syntax:
http://<servername>/axis-cgi/disks/repair.cgi?<argument>=<value>
[&<argument>=<value>...]

With the following arguments and values:

ArgumentValid valuesDescription
diskid=<string><Disk ID>The Disk ID of the disk to be repaired. Required.

Response

Responses from disks/repair.cgi

Success:

HTTP code

200 OK

Content-type

text/xml

Body:
<?xml version="1.0" ?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation=
    "http://www.axis.com/vapix/http_cgi/disk/startjob1.xsd">
  <job action="repair"
    diskid="[Disk ID]"
    result="OK"
    jobid="[ID of the started job]"/>
</root>

Error:

HTTP code

200 OK

Content-type

text/xml

Body:
<?xml version="1.0" ?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation=
    "http://www.axis.com/vapix/http_cgi/disk/startjob1.xsd">
  <job action="repair"
    diskid="[Disk ID]"
    result="ERROR"
    description="[error description]"/>
</root>

Supported elements, attributes and values:

ElementDescriptionAttributeDescription
jobInformation about the job.action="repair"The requested action: repair
diskidThe Disk ID.
resultResult of the request.
OK = The repair job was started successfully.
ERROR = The repair job could not be started.
jobidThe Job ID.
descriptionError description.

Mount and unmount a disk

Use disks/mount.cgi to mount a disk to the system and to unmount a disk from the system.

Important
To prevent corruption of recordings, SD cards should always be unmounted before being ejected.

The response shows if the job has been started or not. A successfully started job returns a Job ID, which should be used as input to job.cgi, see Job progress.

Mounting is done automatically:

  • when an SD card is inserted

  • when a network share is bound to a disk

  • when the system boots (provided that an SD is inserted or a network share has been bound)

A manual mount is only required if a disk has been unmounted and not automatically remounted (for example by a system restart).

Unmounting makes the disk unavailable to the system. A disk that has been unmounted can be safely removed from the product.

Request

Access control

admin

Method

GET

Syntax:
http://<servername>/axis-cgi/disks/mount.cgi?<argument>=<value>
[&<argument>=<value>...]

With the following arguments and values:

ArgumentValid valuesDescription
action=<string>mount
unmount
Required. Specify the action to perform.
mount = Mount the disk.
unmount= Unmount the disk.
diskid=<string><Disk ID>Required. Specify the Disk ID of the disk to be mounted or unmounted.

Response

Responses from disks/mount.cgi

Success:

HTTP code

200 OK

Content-type

text/xml

Body:
<?xml version="1.0" ?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation=
    "http://www.axis.com/vapix/http_cgi/disk/startjob1.xsd">
  <job action="[requested action]"
    diskid="[Disk ID]"
    result="OK"
    jobid="[ID of the started job]"/>
</root>

Error:

HTTP code

200 OK

Content-type

text/xml

Body:
<?xml version="1.0" ?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation=
    "http://www.axis.com/vapix/http_cgi/disk/startjob1.xsd">
  <job action="[requested action]"
    diskid="[Disk ID]"
    result="ERROR"
    description="[error description]"/>
</root>

Supported elements, attributes and values:

ElementDescriptionAttributeDescription
jobInformation about the job.actionThe requested action:
mount
unmount
diskidThe Disk ID.
resultResult of the request.
OK = The job was started successfully
ERROR = The job could not be started.
jobidThe Job ID.
descriptionError description.

Job progress

Use disks/job.cgi to check the progress of a format, check disk, repair, mount or unmount job.

The job should be started by running one of format.cgi, checkdisk.cgi, repair.cgi and mount.cgi. If the job could be started successfully, a Job ID is returned. This Job ID is used as input to job.cgi. Typically, job.cgi is run repeatedly until the job is finished. This workflow allows a user interface to be more responsive and to report the progress of a job by displaying incremental status updates, for example in a progress bar.

Request

Access control

admin, operator

Method

GET

Syntax:
http://<servername>/axis-cgi/disks/job.cgi?<argument>=<value>[&<argument>=<value>...]

With the following arguments and values:

ArgumentValid valuesDescription
jobid=<integer><Job ID>Required. The ID of the job to check.
diskid=<string><Disk ID>Required. The Disk ID of the disk to check.

Response

Responses from disks/job.cgi

Success:

HTTP code

200 OK

Content-type

text/xml

Body:
<?xml version="1.0" ?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation=
    "http://www.axis.com/vapix/http_cgi/disk/checkjob1.xsd">
  <job jobid="[ID of the started job]"
    diskid="[Disk ID]"
    action="[requested action]"
    result="OK"
    progress="[percentage done]"
    description="[result description]"/>
</root>

Error:

HTTP code

200 OK

Content-type

text/xml

Body:
<?xml version="1.0" ?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation=
    "http://www.axis.com/vapix/http_cgi/disk/checkjob1.xsd">
  <job jobid="[ID of the started job]"
    diskid="[Disk ID]"
    action="[current action]"
    progress="100"
    result="ERROR"
    description="[error description]"/>
</root>

Supported attributes and values:

ElementDescriptionAttributeDescription
jobContains the result or progress of the job.jobidThe Job ID.
diskidThe Disk ID.
actionThe requested job:
format = Format the disk.
checkdisk = Check disk.
repair = Repair the disk.
mount = Mount the disk.
unmount = Unmount the disk.
N/A = Not applicable.
progressProgress in percent.
resultResult of the request.
OK = The job is in progress or is finished successfully.
ERROR = An error was found.
descriptionDescription of the result or the error.

Lock or unlock a disk

Use disks/lock.cgi to lock or unlock a disk. When locked, all active recording are stopped and saved recordings cannot be removed. A locked disk cannot be formatted or written to.

Request

Access control

admin

Method

GET

Syntax:
http://<servername>/axis-cgi/disks/lock.cgi?<argument>=<value>
[&<argument>=<value>...]

With the following arguments and values:

ArgumentValid valuesDescription
action=<string>lock
unlock
Required. The action to perform.
lock = Lock the disk.
unlock = Unlock the disk.
diskid=<string><Disk ID>Required. The Disk ID of the disk to be locked or unlocked.

Response

Responses from disks/lock.cgi

Return:

HTTP code

200 OK

Content-type

text/xml

Body:
<?xml version="1.0" ?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation=
    "http://www.axis.com/vapix/http_cgi/disk/lock1.xsd">
  <lock diskid="[Disk ID]"
    result="OK"/>
</root>

or

Body:
<?xml version="1.0" ?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation=
    "http://www.axis.com/vapix/http_cgi/disk/lock1.xsd">
  <unlock diskid="[Disk ID]"
    result="OK"/>
</root>

Supported attributes and values:

ElementDescriptionAttributeDescription
lockThe requested action: lockdiskidThe Disk ID
resultOK = The disk was locked successfully
unlockThe requested action: unlockdiskidThe Disk ID
resultOK = The disk was unlocked successfully

Get disk capabilities

Use disks/getcapabilities.cgi to list the capabilities supported by the disk. The response shows the file systems that the disk can be formatted with, if required file system is supported and if disk encryption is supported.

Request

Access control

admin, operator

Method

GET

Syntax:
http://<servername>/axis-cgi/disks/getcapabilities.cgi?<argument>=<value>
[&<argument>=<value>...]

With the following arguments and values:

ArgumentValid valuesDescription
diskid=<string><Disk ID>Required. The Disk ID.

Response

Responses from disks/getcapabilities.cgi

HTTP code

200 OK

Content-type

text/xml

Body:
<?xml version="1.0" ?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation=
    "http://www.axis.com/vapix/http_cgi/disk/capabilities1.xsd">
  <disk diskid="[Disk ID]" requiredfssupported="[true|false]" encryptionsupported="[true|false]">
    <filesystems> 
      <filesystem 
          name="[filesystem 1]" 
          nicename="[filesystem 1]" 
          requiredfssupported="[true|false]"/>
      <filesystem 
          name="[filesystem 2]" 
          nicename="[filesystem 2]" 
          requiredfssupported="[true|false]"/>
      ...
    </filesystems> 
  </disk>
</root>

Supported elements, attributes and values:

ElementDescriptionAttributeDescription
diskContains information about the diskdiskidThe Disk ID
requiredfssupported

true = The disk supports required file system.

false = The disk does not support required file system.

encryptionsupported

true = The disk supports disk encryption.

false = The disk does not support disk encryption.

filesystemsLists all file systems that the disk can be formatted with.
filesystemContains information about one file systemnameFile system name
nicenameDescriptive name of the file system.
requiredfssupported

true = The file system can be used as required file system.

false = The file system cannot be used as required file system.

Get disk health

Use gethealth.cgi to list the health status (wear level, temperature and overall health) of all disks.

Note: Requires Firmware 7.20 and later.

Request

Access control

admin, operator

Method

GET

Syntax
http://<servername>/axis-cgi/disks/gethealth.cgi

Response

HTTP code

200 OK

Content-type

text/xml

Success
<?xml version="1.0" encoding="UTF-8"?>
<HealthStatusResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/disk/gethealth1.xsd">
  <HealthStatusSuccess>
    <HealthStatus diskid="SD_DISK" wear="25"/>
    <HealthStatus diskid="NetworkShare" wear="-1"/>
    <HealthStatus diskid="HDD_DISK" wear="13" temperature="315" overallhealth="1"/>
  </HealthStatusSuccess>
</HealthStatusResponse>

The wear attribute value shows how much of the disk's expected life span (in percent) that has passed. The value can exceed 100 percent.

The temperature attribute value shows the disk temperature in Kelvin degrees (315 degrees Kelvin = 42 degrees Celsius). Note: Firmware 9.50 and later.

The overallhealth attribute value shows the overall health status for the device (0 = FAIL, 1 = PASSED). Note: Firmware 9.50 and later.

The Health Status attributes can also have one of the following negative values: -1 means that the feature is not supported for the disk, -2 means that an error occured, -3 means that the disk is not present.

Error
<?xml version="1.0" ?>
<HealthStatusResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/disk/gethealth1.xsd">
  <GeneralError>
    <ErrorCode[code]/ErrorCode>
    <ErrorDescription[description]/ErrorDescription>
  </GeneralError>
</HealthStatusResponse>
Possible values for the ErrorCode element:
Error codeDescription
10An error occurred while processing the request.

Disk properties API

Description

VAPIX® Disk properties API is used to configure various disk properties. The API consists of the following CGIs:

setrequiredfs.cgiEnable and set required file system. Required file system is used to automatically format SD cards. See Set required file system.
enablediskencryption.cgiEnable disk encryption. Disk encryption is used to encrypt the SD card content in order to prevent unauthorized systems and individuals to access recorded video. See Enable disk encryption.
disablediskencryption.cgiDisable disk encryption. See Disable disk encryption.
changediskpassphrase.cgiChange the disk encryption passphrase. See Change disk encryption passphrase.
schemaversions.cgiRetrieve a list of supported versions of the XML schema for the Disk Properties API.

Prerequisites

Identification

Required file system is supported if

Property

Properties.LocalStorage.RequiredFileSystem=yes

Disk encryption is supported if

Property

Properties.LocalStorage.DiskEncryption=yes

Required file system

Check if required file system has been set.

http://myserver/axis-cgi/disks/list.cgi?diskid=SD_DISK

The response shows that required file system is disabled.

Response:
HTTP/1.0 200 OK
Content-Type: text/xml
 
<?xml version="1.0" ?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation=
    "http://www.axis.com/vapix/http_cgi/disk/list1.xsd">
  <disks numberofdisks="1">
    <disk diskid="SD_DISK"
      name="My SD Card" 
      totalsize="2097152"
      freesize="2097152"
      cleanuplevel="95"
      cleanupmaxage="1"
      cleanuppolicy="none"
      locked="no"
      full="no"
      readonly="no"
      filesystem="vfat"
      status="OK"
      group="S0"
      requiredfilesystem="none"
      diskencryptionenabled="false"
      diskencrypted="false"/>
  </disks>
</root>

Check if the disk supports required file system.

http://myserver/axis-cgi/disks/getcapabilities.cgi?diskid=SD_DISK

The response shows that required file system is supported and that ext4 can be used as required file system.

Response:
HTTP/1.0 200 OK
Content-Type: text/xml
 
<?xml version="1.0" encoding="UTF-8"?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation=
    "http://www.axis.com/vapix/http_cgi/disk/capabilities1.xsd”>
  <disk diskid="SD_DISK" requiredfssupported="true" encryptionsupported="true">
    <filesystems>
      <filesystem name="vfat" nicename=" " requiredfssupported="false"/>
      <filesystem name="ext4" nicename=" " requiredfssupported="true"/>
    </filesystems>
  </disk>
</root>

Set required file system to ext4.

http://myserver/axis-cgi/disks/properties/setrequiredfs.cgi
?schemaversion=1&diskid=SD_DISK&filesystem=ext4

Disable required file system.

http://myserver/axis-cgi/disks/properties/setrequiredfs.cgi
?schemaversion=1&diskid=SD_DISK&filesystem=none

Disk encryption

Check if the disk supports disk encryption.

Request:
http://myserver/axis-cgi/disks/getcapabilities.cgi?diskid=SD_DISK

The response shows that disk encryption is supported.

Response:
HTTP/1.0 200 OK
Content-Type: text/xml
 
<?xml version="1.0" encoding="UTF-8"?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/disk/capabilities1.xsd">
  <disk diskid="SD_DISK" requiredfssupported="true" encryptionsupported="true">
    <filesystems>
      <filesystem name="vfat" nicename=" " requiredfssupported="false"/>
      <filesystem name="ext4" nicename=" " requiredfssupported="true"/>
    </filesystems>
  </disk>
</root>

Enable disk encryption. Before disk encryption can be enabled, the disk must be unmounted. After enabling disk encryption the disk must be mounted and formatted before it can be used. If required file system is set, the disk is formatted automatically.

Unmount the SD card. For detailed information about the request, see Mount and unmount a disk.

Request:
http://myserver/axis-cgi/disks/mount.cgi?action=unmount&diskid=SD_DISK
Response:
HTTP/1.0 200 OK
Content-Type: text/xml
 
<?xml version="1.0" encoding="UTF-8"?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/disk/startjob1.xsd">
  <job action=unmount
    diskid="SD_DISK"
    result="OK"
    jobid="10"/>
</root>

Enable disk encryption and set the password to secret. For detailed information about the request, see Enable disk encryption.

Request:
http://myserver/axis-cgi/disks/properties/enablediskencryption.cgi?schemaversion=1
&diskid=SD_DISK&passphrase=secret
Response:
HTTP/1.0 200 OK
Content-Type: text/xml
 
<?xml version="1.0" encoding="UTF-8"?>
<DiskPropertiesResponse xmlns="http://www.axis.com/vapix/http_cgi/disks/properties1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.axis.com/vapix/http_cgi/disks/properties1http://www.axis.com/vapix/http_cgi/disks/properties/disk_properties1.xsd" SchemaVersion="1.0">
  <Success>
    <GeneralSuccess />
  </Success>
</DiskPropertiesResponse>

Mount the disk:

Request:
http://myserver/axis-cgi/disks/mount.cgi?action=mount&diskid=SD_DISK
Response:
HTTP/1.0 200 OK
Content-Type: text/xml
 
<?xml version="1.0" encoding="UTF-8"?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/disk/startjob1.xsd">
  <job action=mount
    diskid="SD_DISK"
    result="OK"
    jobid="11"/>
</root>

Format the disk. If required file system is set, the disk is formatted automatically when mounted and this step should be skipped. For detailed information about the request, see Format disk.

Request:
http://myserver/axis-cgi/disks/format.cgi?diskid=SD_DISK&filesystem=ext4
Response:
HTTP/1.0 200 OK
Content-Type: text/xml
 
<?xml version="1.0" encoding="UTF-8"?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/disk/startjob1.xsd">
  <job action=format
    diskid="SD_DISK"
    result="OK"
    jobid="12"/>
</root>

Disable disk encryption. Before disk encryption can be disabled, the disk must be unmounted. After disabling disk encryption the disk must be mounted and formatted before it can be used. If required file system is set, the disk is formatted automatically. Note that recordings will be removed when the disk is formatted.

Unmount the SD card. For detailed information about the request, see Mount and unmount a disk.

Request:
http://myserver/axis-cgi/disks/mount.cgi?action=unmount&diskid=SD_DISK
Response:
HTTP/1.0 200 OK
Content-Type: text/xml
 
<?xml version="1.0" encoding="UTF-8"?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/disk/startjob1.xsd">
  <job action=unmount
    diskid="SD_DISK"
    result="OK"
    jobid="10"/>
</root>

Disable disk encryption. For detailed information about the request, see Disable disk encryption.

Request:
http://myserver/axis-cgi/disks/properties/disablediskencryption.cgi?schemaversion=1&diskid=SD_DISK
Response:
HTTP/1.0 200 OK
Content-Type: text/xml
 
<?xml version="1.0" encoding="UTF-8"?>
<DiskPropertiesResponse xmlns="http://www.axis.com/vapix/http_cgi/disks/properties1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.axis.com/vapix/http_cgi/disks/properties1http://www.axis.com/vapix/http_cgi/disks/properties/disk_properties1.xsd" SchemaVersion="1.0">
  <Success>
    <GeneralSuccess />
  </Success>
</DiskPropertiesResponse>

Mount the disk:

Request:
http://myserver/axis-cgi/disks/mount.cgi?action=mount&diskid=SD_DISK
Response:
HTTP/1.0 200 OK
Content-Type: text/xml
 
<?xml version="1.0" encoding="UTF-8"?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/disk/startjob1.xsd">
  <job action=mount
    diskid="SD_DISK"
    result="OK"
    jobid="11"/>
</root>

Format the disk. If required file system is set, the disk is formatted automatically when mounted and this step should be skipped. For detailed information about the request, see Format disk.

Request:
http://myserver/axis-cgi/disks/format.cgi?diskid=SD_DISK&filesystem=ext4
Response:
HTTP/1.0 200 OK
Content-Type: text/xml
 
<?xml version="1.0" encoding="UTF-8"?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/disk/startjob1.xsd">
  <job action=format
    diskid="SD_DISK"
    result="OK"
    jobid="12"/>
</root>

Change the passphrase. The passphrase can only be changed when the disk is mounted. If the disk is unmounted, use disks/mount.cgi to mount the disk.

Request:
http://myserver/axis-cgi/disks/properties/changediskpassphrase.cgi?schemaversion=1
&diskid=SD_DISK&newpassphrase=verysecret&oldpassphrase=secret
Response:
HTTP/1.0 200 OK
Content-Type: text/xml
 
<?xml version="1.0" encoding="UTF-8"?>
<DiskPropertiesResponse xmlns="http://www.axis.com/vapix/http_cgi/disks/properties1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.axis.com/vapix/http_cgi/disks/properties1http://www.axis.com/vapix/http_cgi/disks/properties/disk_properties1.xsd" SchemaVersion="1.0">
  <Success>
    <GeneralSuccess />
  </Success>
</DiskPropertiesResponse>

Set required file system

Use disks/properties/setrequiredfs.cgi to enable and set a required file system for the disk. Required file system is disabled by default.

Required file system is used to automatically format SD cards to the file system set as required file system.

If required file system has been set, the Axis product checks each mounted SD card to see if the card uses the required file system. If the card uses another file system, or if the file system cannot be determined, the card is formatted to the required file system automatically. During formatting, any data on the card is lost.

An SD card that has been locked (using the switch on the card or using disks/lock.cgi) is not reformatted. If the card is unlocked using disks/lock.cgi, the card will be formatted the next time it is mounted.

If a required file system is set while a card is mounted and in use, the card will be reformatted when it is remounted and all data will be lost.

Note
  • To check the current required file system setting, use disks/list.cgi. See List disks.

  • Before setting a required file system, use disks/getcapabilities.cgi to check if the intended file system can be used as required file system. See Get disk capabilities.

  • Required file system can be set to ext4. Using ext4 is recommended to reduce the risk of data loss if the card is ejected and after abrupt power cycling. To read SD cards formatted with ext4 on Windows, additional software is needed.

  • In the Axis product web interface, the required file system setting is called autoformat.

  • Request

    Access control

    admin

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/disks/properties/setrequiredfs.cgi?<argument>=<value>
    [&<argument>=<value>...]

    With the following arguments and values:

    ArgumentValid valuesDescription
    schemaversion=<integer>Integer

    Required. The major version of the XML Schema to use for the response. See XML schemas.

    diskid=<string><Disk ID>Required. The Disk ID of the disk to set required file system on.
    filesystem=<integer>none
    ext4

    Required. The file system to use as required file system. Supported file systems can be requested using disks/getcapabilities.cgi as described in Get disk capabilities.

    none = Disable the required file system functionality.

    Response

    Responses from disks/properties/setrequiredfs.cgi

    Success

    If the request is successful, required file system is set and a Success response is returned. See General success response.

    Error

    If an error occurred, an Error response is returned. See General error response.

    Error codes: 10, 20, 30, 40

    Enable disk encryption

    Use disks/properties/enablediskencryption.cgi to enable disk encryption.

    Disk encryption is disabled by default. Disk encryption can only be enabled when the disk is unmounted. After enabling disk encryption, the disk must be formatted and mounted. See Disk encryption.

    Request

    Access control

    admin

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/disks/properties/enablediskencryption.cgi?<argument>=<value>&[<argument>=<value>...]

    with the following arguments and values:

    ArgumentValid valuesDescription
    schemaversion=<integer>Integer

    Required. The major version of the XML Schema to use for the response. See XML schemas.

    diskid=<string><Disk ID>

    Required. Disk ID of the disk to encrypt.

    passphrase=<string>String

    Required. The passphrase to use for disk encryption.

    Maximum length: 512 bytes

    Response

    Responses from disks/properties/enablediskencryption.cgi

    Success

    If the request is successful, the disk content is encrypted and a Success response is returned. See General success response.

    Error

    If an error occurred, an Error response is returned. See General error response.

    Error codes: 10, 20, 40, 50, 100, 110, 140, 160

    Disable disk encryption

    Use disks/properties/disablediskencryption.cgi to disable disk encryption.

    Disk encryption can only be disabled when the disk is unmounted. After disabling disk encryption, the disk must be mounted and formatted.

    Request

    Access control

    admin

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/disks/properties/disablediskencryption.cgi?<argument>=<value>&[<argument>=<value>...]

    with the following arguments and values:

    ArgumentValid valuesDescription
    schemaversion=<integer>Integer

    Required. The major version of the XML Schema to use for the response. See XML schemas.

    diskid=<string><Disk ID>

    Required. The disk’s Disk ID.

    Response

    Responses from disks/properties/disablediskencryption.cgi

    Success

    If the request is successful, disk encryption is disabled and a Success response is returned. See General success response.

    Error

    If an error occurred, an Error response is returned. See General error response.

    Error codes: 10, 20, 40, 50, 100, 160

    Change disk encryption passphrase

    Use disks/properties/changediskpassphrase.cgi to change the passphrase used for disk encryption. The passphrase can only be changed when the disk is mounted. Changing the passphrase does not disrupt ongoing recordings.

    Request

    Access control

    admin

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/disks/properties/changediskpassphrase.cgi?<argument>=<value>&[<argument>=<value>...]

    with the following arguments and values:

    ArgumentValid valuesDescription
    schemaversion=<integer>Integer

    Required. The major version of the XML Schema to use for the response. See XML schemas.

    diskid=<string><Disk ID>

    Required. The disk’s Disk ID.

    newpassphrase=<string>String

    Required. The new passphrase to use for disk encryption.

    Maximum length: 512 bytes

    oldpassphrase=<string>String

    Required. The current passphrase.

    Response

    Responses from disks/properties/changediskpassphrase.cgi

    Success

    If the request is successful, disk encryption is disabled and a Success response is returned. See General success response.

    Error

    If an error occurred, an Error response is returned. See General error response.

    Error codes: 10, 20, 40, 50, 100, 120, 130, 150

    Update cleanup max age

    Use disks/properties/setcleanupmaxage.cgi to update the current cleanup max age setting.

    Request

    Access control

    admin

    Method

    GET

    Syntax
    http://<servername/axis-cgi/disks/properties/setcleanupmaxage.cgi?<argument=value>
    ArgumentValid valuesDescription
    schema versionIntegerRequired. The major version of the XML Schema to use for the response. See XML schemas.
    diskidStringRequired. The disk’s Disk ID.
    maxage0–7000Required. The maximum number of days that the unlocked recordings are kept on the disk itself. Recordings older than the specified number will be deleted. This parameter is only used when CleanupPolicy is set to fifo.

    Please note that recordings will be deleted if the free amount of storage space becomes low.

    Response

    Responses from disks/properties/setcleanupmaxage.cgi

    Success

    If the request is successful, the disk content is encrypted and a Success response is returned. See General success response.

    Error

    If an error occurred, an Error response is returned. See General error response.

    Error codes: 10, 20, 40, 50, 100, 110, 140, 160

    Update cleanup policy

    Use disks/properties/setcleanuppolicy.cgi to update the current cleanup policy setting.

    Request

    Access control

    admin

    Method

    GET

    Syntax
    http://<servername/axis-cgi/disks/properties/setcleanuppolicy.cgi?<argument=value>
    ArgumentValid valuesDescription
    schema versionIntegerRequired. The major version of the XML Schema to use for the response. See XML schemas.
    diskidStringRequired. The disk’s Disk ID.
    cleanuppolicyfifo
    none
    Required.

    fifo = first in, first out. Recordings are automatically deleted according to the rules specified by cleanupmaxage.


    none = Recordings must be manually deleted.


    Please note that recordings will be deleted if the free amount of storage space becomes low

    Response

    Responses from disks/properties/setcleanuppolicy.cgi

    Success

    If the request is successful, the disk content is encrypted and a Success response is returned. See General success response.

    Error

    If an error occurred, an Error response is returned. See General error response.

    Error codes: 10, 20, 40, 50, 100, 110, 140, 160

    Set disk alert levels

    Use disks/properties/setdiskalertlevels.cgi to update the alert levels for a disk.

    Request

    Access control

    admin

    Method

    GET

    Syntax
    http://<servername>/axis-cgi/disks/properties/setdiskalertlevels.cgi?<argument=value>&[<argument=value>...]

    with the following arguments and values:

    ArgumentValid valuesDescription
    schemaversion=<integer>IntegerRequired. The major version of the XML Schema to use for the response. See XML schemas.
    diskid=<string>StringRequired. The disk’s Disk ID.
    wear>=0The wear level of the disk that should trigger a storage alert event. The event will be sent once with the alert property set to True when any property reaches its alert level. Once all properties are below their alert levels for the event will be sent again, but with the alert property set to False.
    temperature>=0The temperature, measured in Kelvin, of the disk at which to trigger a Storage alert event. This event is sent once with the alert property set to True when any property reaches its alert level. Once all properties are below their alert levels for the event will be sent again, but with the alert property set to False.

    Response

    Responses from disks/properties/setdiskalertlevels.cgi

    Success

    If the request is successful, the disk content is encrypted and a Success response is returned. See General success response.

    Error

    If an error occurred, an Error response is returned. See General error response.

    Error codes: 10, 20, 40, 50, 100, 110, 140, 160

    Get disk alert levels

    Use disks/properties/getdiskalertlevels.cgi to check the alert levels for a disk.

    Request

    Access control

    admin

    Method

    GET

    Syntax
    http://<servername>/axis-cgi/disks/properties/getdiskalertlevels.cgi?<argument=value>&[<argument=value>...]

    with the following arguments and values:

    ArgumentValid valuesDescription
    schemaversionIntegerRequired. The major version of the XML schema to use for the response. See XML schemas.
    diskidStringRequired. The disk’s Disk ID.

    Response

    Responses from disks/properties/getdiskalertlevels.cgi

    Success

    Successful response
    HTTP/1.0 200 OK
    Content-Type: text/xml
    
    <DiskPropertiesResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/disks/properties/disk_properties1.xsd" SchemaVersion="1.1">
      <Success>
        <GetAlertLevelsSuccess>
          <AlertLevels Wear="50" Temperature="360"/>
        </GetAlertLevelsSuccess>
      </Success>
    </DiskPropertiesResponse>

    Error

    If an error occurred, an Error response is returned. See General error response.

    Error codes: 10, 20, 40, 50, 100, 110, 140, 160

    XML schema versions

    Use disks/properties/schemaversions.cgi to list supported versions of the XML schema for the Disk properties API and whether the schemas are deprecated or not.

    Request

    Access control

    admin, operator

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/disks/properties/schemaversions.cgi

    This CGI has no arguments.

    Response

    Responses from disks/properties/schemaversions.cgi

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" encoding="utf-8"?>
    <DiskPropertiesResponse 
        xmlns="http://www.axis.com/vapix/http_cgi/disks/properties1" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:schemaLocation=
        "http://www.axis.com/vapix/http_cgi/disks/properties1
        http://www.axis.com/vapix/http_cgi/disks/properties/disk_properties1.xsd"
        SchemaVersion="1.0">
      <Success>
        <SchemaVersionsSuccess>
          <SchemaVersion>
            <VersionNumber>[major.minor]</VersionNumber>
            <Deprecated>[true/false]</Deprecated>
            ...
          </SchemaVersion>
        </SchemaVersionsSuccess>
      </Success>
    </DiskPropertiesResponse>

    Supported elements, attributes and values:

    ElementDescription
    DiskPropertiesResponseContains the response. For information about XML schema versions, see XML schemas.
    SuccessSuccessful request
    SchemaVersionsSuccessContains the supported XML schema versions.
    SchemaVersionContains one schema version.
    VersionNumber

    Schema version. See XML schemas.

    Deprecated

    If true, this version of the XML Schema is deprecated and should not be used.

    General success response

    General success response from Disk Properties API.

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" encoding="UTF-8"?>
    <DiskPropertiesResponse xmlns="http://www.axis.com/vapix/http_cgi/disks/properties1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.axis.com/vapix/http_cgi/disks/properties1http://www.axis.com/vapix/http_cgi/disks/properties/disk_properties1.xsd" SchemaVersion="1.0">
      <Success>
        <GeneralSuccess />
      </Success>
    </DiskPropertiesResponse>

    Supported elements, attributes and values:

    ElementDescription
    DiskPropertiesResponseContains the response. For information about XML schema versions, see XML schemas.
    SuccessSuccessful request.
    GeneralSuccessSuccessful request.

    General error response

    General error response from the Disk properties API.

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" encoding="utf-8"?>
    <DiskPropertiesResponse xmlns="http://www.axis.com/vapix/http_cgi/disks/properties1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.axis.com/vapix/http_cgi/disks/properties1http://www.axis.com/vapix/http_cgi/disks/properties/disk_properties1.xsd" SchemaVersion="1.0">
      <Error>
        <GeneralError>
          <ErrorCode>[error code]</ErrorCode>
          <ErrorDescription>[description]</ErrorDescription>
        </GeneralError>
      </Error>
    </DiskPropertiesResponse>

    Supported elements, attributes and values:

    ElementDescription
    DiskPropertiesResponseContains the response. For information about XML schema versions, see XML schemas.
    ErrorError response.
    GeneralErrorError response.
    ErrorCodeA numeric error code. See table below.
    ErrorDescriptionDescription of the error.
    Error codeDescriptionCGI
    10Error while processing the request.All
    20Invalid request.All
    30Specified file system is not supported.setrequiredfs.cgi
    40Specified version is not supported.All
    50Invalid disk ID.

    enablediskencryption.cgi

    disablediskencryption.cgi

    changediskpassphrase.cgi

    100The disk does not support disk encryption.

    enablediskencryption.cgi

    disablediskencryption.cgi

    changediskpassphrase.cgi

    110Invalid passphrase.

    enablediskencryption.cgi

    120Invalid new passphrase.

    changediskpassphrase.cgi

    130The oldpassphrase does not match the existing passphrase.

    changediskpassphrase.cgi

    140Encryption is already enabled.

    enablediskencryption.cgi

    150The disk is unmounted. Passphrase can only be changed when the disk is mounted.

    changediskpassphrase.cgi

    160The disk is mounted. Encryption can only be enabled/disabled when the disk is unmounted.

    enablediskencryption.cgi

    disablediskencryption.cgi

    Network share API

    Description

    Use VAPIX® Network share API to add, remove and manage network shares. A network share can be a share on a NAS (Network Attached Storage) or on any server that uses CIFS (Common Internet File System), also known as SMB (Server Message Block).

    The Axis product identifies the share using a unique Share ID. The share ID is assigned to the share by the Axis product but can also be set manually when adding the share.

    To store recordings on a network share, the share must be bound to a disk. The bind request returns a Disk ID which should be used when setting up and accessing recordings. For information about recordings, see Recording API.

    The Network share API consists of the following CGIs:

    list.cgiList the added network shares and their parameters.
    add.cgiAdd a network share.
    modify.cgiModify a network share. The network share must first be unbound.
    remove.cgiRemove a network share. The network share must first be unbound.
    bind.cgiBind the network share to a disk. This makes it possible to access the share through the Disk Management API, see Disk management API.
    unbind.cgiUnbind the network share.
    test.cgiTest the network share to verify that the parameters are correct and that the share can be used as a storage device. A successfully started test returns a Job ID which should be used as input to job.cgi.
    job.cgiCheck the progress of a job. Typically used repeatedly until the job is done.
    schemaversions.cgiRetrieve a list of supported versions of the XML Schema for the Network Share API.

    Recordings stored on a network share cannot be accessed directly. This is because the Axis product creates an internal database on the share. If recordings need to be accessed directly, create a network share recipient in an action rule instead.

    Prerequisites

    Identification

    Property

    Properties.API.HTTP.Version=3

    Property

    Properties.NetworkShare.NetworkShare=yes

    Property

    Properties.NetworkShare.CIFS=yes

    Firmware

    5.40 and later

    Common examples

    Test that the network share “myshare” on the storage device “mynas” can be used for storage. User name for the share is “nasuser” and password is “pass”.

    http://myserver/axis-cgi/disks/networkshare/test.cgi?schemaversion=1
    &address=mynas.mycompany.com&share=myshare&user=nasuser&pass=pass

    The response returns the Job ID of the started job. Here, the returned Job ID is 1. The Job ID is to be used as input to job.cgi to check the progress of the started job.

    http://myserver/axis-cgi/disks/networkshare/job.cgi?schemaversion=1&jobid=1

    The response shows that the job is in progress, 15% of the job is done.

    Response:
    HTTP/1.0 200 OK
    Content-Type: text/xml
     
    <?xml version="1.0" encoding="utf-8"?>
    <NetworkShareResponse SchemaVersion="1.0" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation=
        "http://www.axis.com/vapix/http_cgi/networkshare1.xsd">
      <JobSuccess>
        <Progress>15</Progress>
      </JobSuccess>
    </NetworkShareResponse>

    By running job.cgi repeatedly, the progress of the job can be reported by showing incremental updates, for example:

    15% 
    32%
    45%
    68%
    92%
    Done!

    Add the network share “myshare” on the storage device “mynas”. User name for the share is “nasuser” and password is “pass”. The network share is given a user-friendly name “My Share”.

    http://myserver/axis-cgi/disks/networkshare/add.cgi?schemaversion=1
    &nicename=My%20Share&address=mynas&share=myshare&user=nasuser&pass=pass

    The share’s unique Share ID is returned in the response. Here, the returned Share ID is 485279c5-6676-4abd-b04c-4434e4791730

    List all network shares.

    http://myserver/axis-cgi/disks/networkshare/list.cgi?schemaversion=1&shareid=all

    The response shows that one network share has been added.

    Response:
    HTTP/1.0 200 OK
    Content-Type: text/xml
     
    <?xml version="1.0" encoding="utf-8"?>
    <NetworkShareResponse SchemaVersion="1.0" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation=
        "http://www.axis.com/vapix/http_cgi/networkshare1.xsd">
      <ListSuccess>
        <NetworkShares NumberOfShares="1">
          <NetworkShare NiceName="My Share" 
            ShareId="35419"
            Address="mynas.mycompany.com"
            Share="myshare"
            User="nasuser" />
        </NetworkShares>
      </ListSuccess>
    </NetworkShareResponse>

    Bind the network share to a disk. The disk is mounted automatically. The Share ID is from the add.cgi response.

    http://myserver/axis-cgi/disks/networkshare/bind.cgi?schemaversion=1
    &shareid=35419

    The Disk ID of the disk to which the share is bound is returned in the response. Here, the returned Disk ID is NetworkShare.

    Unbind and remove the network share.

    http://myserver/axis-cgi/disks/networkshare/unbind.cgi?schemaversion=1
    &shareid=35419
    http://myserver/axis-cgi/disks/networkshare/remove.cgi?schemaversion=1
    &shareid=35419

    List network shares

    Use disks/networkshare/list.cgi to retrieve information about network shares used by the Axis product.

    Request

    Access control

    admin, operator

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/disks/networkshare/list.cgi?<argument>=<value>[&<argument>=<value>...]

    With the following arguments and values:

    ArgumentValid valuesDescription
    schemaversion=<integer>[.<integer>]Integers

    The major version of the XML Schema to use for the response. See XML schemas.

    shareid=<string>all
    <Share ID 1>, <Share ID 2>,...

    Required. The Share IDs of the shares to list.

    all = List all network shares that have been added to the Axis product.

    <Share ID 1>, <Share ID 2> = List shares with the specified Share IDs.

    Response

    The response from disks/networkshare/list.cgi is a list of network shares or a general error.

    Success:

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" encoding="utf-8"?>
    <NetworkShareResponse SchemaVersion="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/networkshare1.xsd">
      <ListSuccess>
        <NetworkShares NumberOfShares="[number of shares]">
          <NetworkShare NiceName="[nicename 1]" 
            ShareId="[Share ID 1]"
            Address="[address 1]"
            Share="[share 1]"
            User="[user 1]"
            DiskId="[Disk ID 1]"/>
          ... 
        </NetworkShares>
      </ListSuccess>
    </NetworkShareResponse>

    Supported elements, attributes and values:

    ElementDescription
    NetworkShareResponse

    Contains the response. For information about XML schema versions, see XML schemas.

    ListSuccess

    Request was successful.

    NetworkShares

    Contains the network shares that have been added.

    NumberOfShares = The number of network shares.

    NetworkShare

    Contains the parameters that define the network share.

    NiceName = User-friendly name for the network share.

    ShareId = The Share ID.

    Address = Network address of the storage device.

    Share = The name of the share on the storage device.

    User = User name for a user on the share.

    DiskId = The Disk ID of the disk to which the share is bound. This attribute is not present if the share is unbound.

    Error

    If an error occurred, a GeneralError response is returned. See General error response.

    Error codes: 10, 20, 40

    Add network share

    Use disks/networkshare/add.cgi to add a network share.

    Request

    Access control

    admin

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/disks/networkshare/add.cgi?<argument>=<value>[&<argument>=<value>...]

    With the following arguments and values:

    ArgumentValid valuesDescription
    schemaversion=<integer>[.<integer>]Integers

    The major version of the XML Schema to use for the response. See XML schemas.

    nicename=<string>String

    Required. A user-friendly name for the network share.

    address=<string>IPv4 address or host name

    Required. The network address of the storage device.

    share=<string>String

    Required. The name of the share on the storage device.

    shareid=<string>String

    A unique Share ID. The ID is restricted to the regular expression [A-Za-z0-9-]+

    user=<string>String

    User name for a user on the share.

    pass=<string>String

    Password for the user above.

    Response

    Responses from disks/networkshare/add.cgi

    Success:

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" encoding="utf-8"?>
    <NetworkShareResponse SchemaVersion="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/networkshare1.xsd">
      <AddSuccess ShareId="[Share ID]" />
    </NetworkShareResponse>

    Supported elements, attributes and values:

    ElementDescription
    NetworkShareResponse

    Contains the response. For information about XML schema versions, see XML schemas.

    AddSuccess

    Successful request.

    ShareId = The Share ID.

    Error

    If an error occurred, a GeneralError response is returned. See General error response.

    Error codes: 10, 20, 40, 200, 210, 220, 230

    Remove network share

    Use disks/networkshare/remove.cgi to remove a network share from the product. Before removing, make sure that the network share is not bound. To unbound the share, use unbind.cgi, see Unbind network share.

    Request

    Access control

    admin

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/disks/networkshare/remove.cgi?<argument>=<value>[&<argument>=<value>...]

    With the following arguments and values:

    ArgumentValid valuesDescription
    schemaversion=<integer>[.<integer>]Integers

    The major version of the XML Schema to use for the response. See XML schemas.

    shareid=<string>
    Required
    <Share ID 1>, <Share ID 2>,...

    Remove the shares with the specified Share IDs.

    Response

    Responses from disks/networkshare/remove.cgi

    Success

    If the request is successful, disk encryption is disabled and a GeneralSuccess response is returned. See General success response.

    Error

    If an error occurred, a GeneralError response is returned. See General error response.

    Error codes: 10, 20, 40, 500

    Modify network share

    Use disks/networkshare/modify.cgi to modify an existing network share. The user-friendly name NiceName can always be changed. To change the other parameters, the share must be unbound from the disk using unbind.cgi, see Unbind network share.

    Request

    Access control

    admin

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/disks/networkshare/modify.cgi?<argument>=<value>[&<argument>=<value>...]

    With the following arguments and values:

    ArgumentValid valuesDescription
    schemaversion=<integer>[.<integer>]Integers

    The major version of the XML Schema to use for the response. See XML schemas.

    shareid=<string>
    Required
    String

    The Share ID of the network share to modify.

    nicename=<string>String

    A user-friendly name for the network share.

    address=<string>IPv4 address or host name

    The network address of the storage device.

    share=<string>String

    The name of the share on the storage device.

    user=<string>String

    User name for a user on the share.

    pass=<string>String

    Password for the user above.

    Response

    Responses from disks/networkshare/modify.cgi

    Success

    If the request is successful, disk encryption is disabled and a GeneralSuccess response is returned. See General success response.

    Error

    If an error occurred, a GeneralError response is returned. See General error response.

    Error codes: 10, 20, 40, 600, 610, 620

    Bind network share

    Use disks/networkshare/bind.cgi to bind an existing network share to a disk. This makes it possible to store recordings on the share and to access the share through the Disk management API. The request returns the Disk ID of the disk to which the share was bound. The Disk ID should be used when setting up and accessing recordings through the Recording API.

    Request

    Access control

    admin, operator

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/disks/networkshare/bind.cgi?<argument>=<value>[&<argument>=<value>...]

    With the following arguments and values:

    ArgumentValid valuesDescription
    schemaversion=<integer>[.<integer>]Integers

    The major version of the XML Schema to use for the response. See XML schemas.

    shareid=<string><Share ID>

    Required. The Share ID of the network share to bind.

    automaticmount=<string>yes
    no

    yes = Turn on automatic mounting. The disk to which the share is bound will be mounted automatically after binding.

    no = Turn off automatic mount. The disk will not be mounted automatically.

    Default: yes.

    Response

    Responses from disks/networkshare/bind.cgi

    Success

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" encoding="utf-8"?>
    <NetworkShareResponse SchemaVersion="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/networkshare1.xsd">
      <BindSuccess DiskID="[Disk ID]"/>
    </NetworkShareResponse>

    Supported elements, attributes and values:

    ElementDescription
    NetworkShareResponse

    Contains the response. For information about XML schema versions, see XML schemas.

    BindSuccess

    Successful request.

    DiskID = The Disk ID of the disk that the network share was bound to.

    Error

    If an error occurred, a GeneralError response is returned. See General error response.

    Error codes: 10, 20, 40, 300, 310

    Unbind network share

    Use disks/networkshare/unbind.cgi to free a bound network share so that the share can be modified or removed.

    Request

    Access control

    admin, operator

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/disks/networkshare/unbind.cgi?<argument>=<value>[&<argument>=<value>...]

    With the following arguments and values:

    ArgumentValid valuesDescription
    schemaversion=<integer>[.<integer>]Integers

    The major version of the XML Schema to use for the response. See XML schemas.

    shareid=<string><Share ID>

    Required. The Share ID of the network share to unbind.

    Response

    Responses from disks/networkshare/unbind.cgi

    Success

    If the request is successful, disk encryption is disabled and a GeneralSuccess response is returned. See General success response.

    Error

    If an error occurred, a GeneralError response is returned. See General error response.

    Error codes: 10, 20, 40, 400

    Test network share

    Use disks/networkshare/test.cgi to test a network share. The submitted parameters specifies the share to test. These parameters are only used to run the test and are not stored. The test checks if the network share can be used as a storage device.

    The response shows if the job has been started or not. A successfully started job returns a Job ID, which should be used as input to job.cgi, see Job progress.

    Request

    Access control

    admin, operator

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/disks/networkshare/test.cgi?<argument>=<value>[&<argument>=<value>...]

    With the following arguments and values:

    ArgumentValid valuesDescription
    schemaversion=<integer>[.<integer>]
    Optional
    Integers

    The major version of the XML Schema to use for the response. See XML schemas.

    address=<string>
    Optional
    IPv4 address or host name

    The network address of the storage device.

    share=<string>
    Optional
    String

    The name of the share on the storage device.

    user=<string>
    Optional
    String

    User name for a user on the share.

    pass=<string>
    Optional
    String

    Password for the user above.

    shareid=<string>
    Optional
    StringA Share ID. shareid can be used instead of one or more of address, share, user and pass.
    If shareid is used together with one or more the above arguments, the specified arguments will override the values stored in the Share ID.

    Response

    Responses from disks/networkshare/test.cgi

    Success

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" encoding="utf-8"?>
    <NetworkShareResponse SchemaVersion="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/networkshare1.xsd">
      <TestSuccess JobId="[Job ID]" />
    </NetworkShareResponse>

    Supported elements, attributes and values:

    ElementDescription
    NetworkShareResponse

    Contains the response. For information about XML schema versions, see XML schemas.

    TestSuccess

    Test was started successfully.

    JobId = The Job ID.

    Error

    If an error occurred, a GeneralError response is returned. See General error response.

    Error codes: 10, 20, 40, 700, 710, 720, 730, 740, 750, 760

    Job progress

    The disks/networkshare/job.cgi is used to check the progress of a test job.

    The test job should be started by running test.cgi. If the job could be started successfully, a Job ID is returned. This Job ID is used as input to job.cgi. The Job ID can also be retrieved by running job.cgi.

    Typically, job.cgi is run repeatedly until the job is finished. This workflow allows a user interface to be more responsive and to report the progress of a job by displaying incremental status updates, for example in a progress bar.

    Request

    Access control

    admin, operator

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/disks/networkshare/job.cgi?<argument>=<value>[&<argument>=<value>...]

    With the following arguments and values:

    ArgumentValid valuesDescription
    schemaversion=<integer>[.<integer>]
    Required
    Integers

    The major version of the XML Schema to use for the response. See XML schemas.

    jobid=<string>
    Required
    <Job ID>

    The ID of the job to check progress for.

    Response

    Responses from disks/networkshare/job.cgi

    Success: Job is in progress

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" encoding="utf-8"?>
    <NetworkShareResponse SchemaVersion="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/networkshare1.xsd">
      <JobSuccess>
        <Progress>[progress]</Progress>
      </JobSuccess>
    </NetworkShareResponse>

    Success: Job finished successfully

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" encoding="utf-8"?>
    <NetworkShareResponse SchemaVersion="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/networkshare1.xsd">
      <JobSuccess>
        <GeneralSuccess />
      </JobSuccess>
    </NetworkShareResponse>

    Success: Job finished but with errors

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" encoding="utf-8"?>
    <NetworkShareResponse SchemaVersion="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/networkshare1.xsd">
      <JobSuccess>
        <GeneralError>
          <ErrorCode>[code]</ErrorCode>
          <ErrorDescription>[description]</ErrorDescription>
        </GeneralError>
      </JobSuccess>
    </NetworkShareResponse>

    Supported elements, attributes and values:

    ElementDescription
    NetworkShareResponse

    Contains the response. For information about XML schema versions, see XML schemas.

    JobSuccess

    Successful request.

    Contains Progress if the job is not finished.

    Contains GeneralSuccess if the job finished successfully.

    Contains GeneralError if the job finished with errors.

    GeneralSuccessThe job finished successfully.
    ProgressProgress of the job in percent.
    GeneralErrorThe job finished with errors.

    Error

    If an error occurred, a GeneralError response is returned. See General error response.

    Error codes: 10, 20, 40, 700, 710, 720, 730, 740, 750, 760

    XML schema versions

    Use disks/networkshare/schemaversions.cgi to list supported versions of the XML schema for the Network share API and whether the schemas are deprecated or not.

    Request

    Access control

    admin, operator

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/disks/networkshare/schemaversions.cgi

    This CGI has no arguments.

    Response

    Responses from disks/networkshare/schemaversions.cgi

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" encoding="utf-8"?>
    <NetworkShareResponse SchemaVersion="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/networkshare1.xsd">
      <SchemaVersionsSuccess>
        <SchemaVersion>
          <VersionNumber>[major1].[minor1]</VersionNumber>
          <Deprecated>[deprecated]</Deprecated>
          ...
        </SchemaVersion>
      </SchemaVersionsSuccess>
    </NetworkShareResponse>

    Supported elements, attributes and values:

    ElementDescription
    NetworkShareResponseContains the response. For information about XML schema versions, see XML schemas.
    SchemaVersionsSuccessContains the supported XML schema versions.
    SchemaVersionContains one schema version.
    VersionNumber

    Schema version. See XML schemas.

    Deprecated

    If true, this version of the XML Schema is deprecated and should not be used.

    General success response

    General success response from Network Share API.

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" encoding="utf-8"?>
    <NetworkShareResponse SchemaVersion="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/networkshare1.xsd">
      <GeneralSuccess />
    </NetworkShareResponse>

    Supported elements, attributes and values:

    ElementDescription
    NetworkShareResponse

    Contains the response. For information about XML schema versions, see XML schemas.

    GeneralSuccess

    Successful request.

    General error response

    General error response from Network share API.

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" encoding="utf-8"?>
    <NetworkShareResponse SchemaVersion="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/networkshare1.xsd">
      <GeneralError>
        <ErrorCode>[error code]</ErrorCode>
        <ErrorDescription>[description]</ErrorDescription>
      </GeneralError>
    </NetworkShareResponse>

    Supported elements, attributes and values:

    ElementDescription
    NetworkShareResponseContains the response. For information about XML schema versions, see XML schemas.
    GeneralErrorError response.
    ErrorCodeA numeric error code. See table below.
    ErrorDescriptionDescription of the error.
    Error codeDescriptionCGI
    10Error while processing the request.All
    20Invalid request.All
    40Specified version is not supported.All
    200Invalid ShareIdadd.cgi
    210The ShareId is not uniqueadd.cgi
    220The NiceName is not uniqueadd.cgi
    230Maximum number of network shares is already reached. No more shares can be added. add.cgi
    300No available disk. Check if another network share is already bound.bind.cgi
    310The network share is already bound to a disk. bind.cgi
    400The network share is mounted and cannot be unbound. Unmount the share using Disk Management API.unbind.cgi
    500 The network share is bound and cannot be removed. Use unbind.cgi to unbind the share.remove.cgi
    600The network share is bound and cannot be modified. Use unbind.cgi to unbind the share.modify.cgi
    610The new ShareID parameter is no unique.modify.cgi
    620The NiceName parameter is not unique.modify.cgi
    700No such hostname.

    test.cgi

    job.cgi

    710Error while mounting network share.

    test.cgi

    job.cgi

    720Internal error while mounting network share.

    test.cgi

    job.cgi

    730Too many tests or jobs started, wait for some to finish.

    test.cgi

    job.cgi

    740Problem writing to the share.

    test.cgi

    job.cgi

    750Problem reading data written to the share.

    test.cgi

    job.cgi

    760Problem connecting to the share.

    test.cgi

    job.cgi

    Recording storage limit API

    Description

    VAPIX® Recording storage limit API allows applications to control how the capacity of a shared storage resource is distributed. For example, when several cameras record to the same network share, the API can be used to limit the amount of disk space each camera is allowed to use.

    Setting recording storage limits is equivalent to setting up quota control on network-attached storage (NAS) devices. The Recording storage limit API enables applications to simplify recording and storage configuration by allowing the camera installer to configure storage limits at the same time and in the same application as the installer configures other recording and storage settings.

    Supported functionality:

    • Retrieve current recording storage limit and currently used disk space.

    • Set recording storage limit.

    Identification

    VAPIX® Recording storage limit API is supported if

    Property

    Properties.LocalStorage.StorageLimit=yes

    Firmware

    5.70 and later

    Common examples

    Get supported XML schema versions.

    Request:
    http://<camera1>/axis-cgi/record/storage/schemaversions.cgi
    Response:
    HTTP/1.0 200 OK
    Content-Type: text/xml
     
    <?xml version="1.0" encoding="utf-8"?>
    <StorageLimitsResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SchemaVersion="1.0" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/recordingstoragelimit1.xsd">
      <SchemaVersionsSuccess>
        <SchemaVersion>
          <VersionNumber>1.0</VersionNumber>
          <Deprecated>false</Deprecated>
        </SchemaVersion>
      </SchemaVersionsSuccess>
    </StorageLimitsResponse>

    Suppose that two cameras should record to the same network share. Use disks/list.cgi to retrieve the network share’s disk space. The response shows that the total disk space is 4000 GB.

    Request:
    http://<camera1>/axis-cgi/disks/list.cgi?diskid=NetworkShare
    Response:
    HTTP/1.0 200 OK
    Content-Type: text/xml
     
    <?xml version="1.0" ?>
    <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/disk/list1.xsd">
      <disks numberofdisks="1">
        <disk diskid="NetworkShare"
          name="My Share" 
          totalsize="4194304000"
          freesize="3670016000"
          cleanuplevel="95"
          cleanupmaxage="1"
          cleanuppolicy="none"
          locked="no"
          full="no"
          readonly="no"
          filesystem="cifs"
          status="OK"
          group="S1"
          requiredfilesystem="none"
          diskencryptionenabled="false"
          diskencrypted="false"/>
      </disks>
    </root>

    Divide the disk space among the two cameras so that one camera uses 2/3 of the disk space and the other camera uses 1/3.

    Requests:
    http://<camera1>/axis-cgi/record/storage/setlimit.cgi?schemaversion=1&diskid=NetworkShare&size=2796202667
     
    http://<camera2>/axis-cgi/record/storage/setlimit.cgi?schemaversion=1&diskid=NetworkShare&size=1398101333
    Responses:
    HTTP/1.0 200 OK
    Content-Type: text/xml
     
    <?xml version="1.0" encoding="utf-8"?>
    <StorageLimitsResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SchemaVersion="1.0" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/recordingstoragelimit1.xsd">
      <GeneralSuccess />
    </StorageLimitsResponse>

    Retrieve the current recording storage limit, that is, the amount of disk space the Axis product is allowed to use. When no diskid is specified, storage limits for all disks are returned. In the response, attribute size contains the current storage limit. Attribute usedspace contains the disk space currently used for recordings. In this example, the SD card has size=0 which means that there is no storage limit for the SD card.

    Request:
    http://<camera1>/axis-cgi/record/storage/getlimit.cgi?schemaversion=1
    Response:
    HTTP/1.0 200 OK
    Content-Type: text/xml
     
    <?xml version="1.0" encoding="utf-8"?>
    <StorageLimitsResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SchemaVersion="1.0" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/recordingstoragelimit1.xsd">
      <GetStorageLimitsResponse>
        <StorageLimit diskid="NetworkShare" size="2796202667" usedspace="553324" />
        <StorageLimit diskid="SD_DISK" size="0" usedspace="661324" />
      </GetStorageLimitsResponse>
    </StorageLimitsResponse>

    To only retrieve the recording storage limit set for the network share, specify the share’s diskid.

    Request:
    http://<camera1>/axis-cgi/record/storage/getlimit.cgi?schemaversion=1&diskid=NetworkShare
    Response:
    HTTP/1.0 200 OK
    Content-Type: text/xml
     
    <?xml version="1.0" encoding="utf-8"?>
    <StorageLimitsResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SchemaVersion="1.0" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/recordingstoragelimit1.xsd">
      <GetStorageLimitsResponse>
        <StorageLimit diskid="NetworkShare" size="2796202667" usedspace="553324" />
      </GetStorageLimitsResponse>
    </StorageLimitsResponse>

    Retrieve the recording storage limit for a non-existing storage device.

    Request:
    http://<camera1>/axis-cgi/record/storage/getlimit.cgi?schemaversion=1&diskid=DUMMY
    Response:
    HTTP/1.0 200 OK
    Content-Type: text/xml
     
    <?xml version="1.0" encoding="utf-8"?>
    <StorageLimitsResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SchemaVersion="1.0" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/recordingstoragelimit1.xsd">
      <GeneralError>
        <ErrorCode>110</ErrorCode>
        <ErrorDescription>Disk not found</ErrorDescription>
      </GeneralError>
    </StorageLimitsResponse>

    Disable recording storage limit for the network share.

    Request:
    http://<camera1>/axis-cgi/record/storage/setlimit.cgi?schemaversion=1&diskid=NetworkShare&size=0
    Response:
    HTTP/1.0 200 OK
    Content-Type: text/xml
     
    <?xml version="1.0" encoding="utf-8"?>
    <StorageLimitsResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SchemaVersion="1.0" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/recordingstoragelimit1.xsd">
      <GeneralSuccess />
    </StorageLimitsResponse>

    Set an incorrect recording storage limit.

    Request:
    http://<camera1>/axis-cgi/record/storage/setlimit.cgi?schemaversion=1&diskid=NetworkShare&size=textstring
    Response:
    HTTP/1.0 200 OK
    Content-Type: text/xml
     
    <?xml version="1.0" encoding="utf-8"?>
    <StorageLimitsResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SchemaVersion="1.0" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/recordingstoragelimit1.xsd">
      <GeneralError>
        <ErrorCode>120</ErrorCode>
        <ErrorDescription>Invalid size value</ErrorDescription>
      </GeneralError>
    </StorageLimitsResponse>

    Get schema versions

    Use record/storage/schemaversions.cgi to retrieve the supported XML schema versions.

    Request

    Access control

    admin, operator

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/record/storage/schemaversions.cgi

    This CGI has no arguments

    Response

    Responses from record/storage/schemaversions.cgi

    Success

    A successful request returns the supported schema versions.

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" encoding="utf-8"?>
    <StorageLimitsResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SchemaVersion="1.0" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/recordingstoragelimit1.xsd">
      <SchemaVersionsSuccess>
        <SchemaVersion>
          <VersionNumber>[major.minor]</VersionNumber>
          <Deprecated>[true/false]</Deprecated>
        </SchemaVersion>
        <SchemaVersion>
          <VersionNumber>[major.minor]</VersionNumber>
          <Deprecated>[true/false]</Deprecated>
        </SchemaVersion>
          [...]
      </SchemaVersionsSuccess>
    </StorageLimitsResponse>

    Supported elements, attributes and values:

    ElementDescription
    StorageLimitsResponseContains the response. For information about XML schema versions, see XML schemas.
    SchemaVersionsSuccessSuccessful request
    SchemaVersionContains the schema version
    VersionNumber

    Schema version. See XML schemas.

    Deprecated

    If true, this version of the XML Schema is deprecated and should not be used.

    Error

    If an error occurred, a GeneralError response is returned. See General error response.

    Error codes: 10, 20, 40

    Get recording storage limit

    Use record/storage/getlimit.cgi to retrieve the current recording storage limit.

    Request

    Access control

    admin, operator

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/record/storage/getlimit.cgi?<argument>=<value>&[<argument>=<value>]

    with the following arguments and values:

    ArgumentValid valuesDescription
    schemaversion=<integer>Integer

    Required. The major version of the XML Schema to use for the response. See XML schemas.

    diskid=<string>String

    Optional. The disk ID of the disk to retrieve storage limit for. If omitted, storage limits for all disks is returned.

    Response

    Responses from record/storage/getlimit.cgi

    Success

    If the request is successful, the recording storage limit for the specified disks is returned.

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" encoding="utf-8"?>
    <StorageLimitsResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SchemaVersion="1.0" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/recordingstoragelimit1.xsd">
      <GetStorageLimitsResponse>
        <StorageLimit diskid="[Disk ID]" size="[size]" usedspace="[used size]" />
        <StorageLimit diskid="[Disk ID]" size="[size]" usedspace="[used size]" />
      </GetStorageLimitsResponse>
    </StorageLimitsResponse>

    Supported elements, attributes and values:

    ElementDescriptionAttributeDescription
    StorageLimitsResponseContains the response. For information about XML schema versions, see XML schemas.
    GetStorageLimitsResponseSuccessful request
    StorageLimitContains the storage limit for one disk.diskidThe disk ID.
    size

    The set recording storage limit size. Unit: kilobytes.

    0 = recording storage limit is disabled.

    usedsize

    Space already used by recording data. Unit: kilobytes.

    Error

    If an error occurred, a GeneralError response is returned. See General error response.

    Error codes: 10, 20, 40, 110

    Set recording storage limit

    Use record/storage/setlimit.cgi to set the recording storage limit, that is, the amount of disk space the Axis product is allowed to use.

    Request

    Access control

    admin, operator

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/record/storage/setlimit.cgi?<argument>=<value>&[<argument>=<value>]

    with the following arguments and values:

    ArgumentValid valuesDescription
    schemaversion=<integer>Integer

    Required. The major version of the XML Schema to use for the response. See XML schemas.

    diskid=<string>String

    Required. The Disk ID of the disk to use.

    size=<string>Integer

    Required. The recording storage limit to set. Unit: kilobytes.

    Use size=0 to disable recording storage limit for the disk.

    Minimum allowed size is 1048576 kilobytes, that is, 1 GB.

    Response

    Responses from record/storage/setlimit.cgi

    Success

    If the request is successful, the recording storage limit is set and a GeneralSuccess response is returned. See General success response.

    Error

    If an error occurred, a GeneralError response is returned. See General error response.

    Error codes: 10, 20, 40, 110, 120, 130

    General success response

    General success response from Recording storage limit API.

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" encoding="UTF-8"?>
    <StorageLimitsResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SchemaVersion="1.0" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/recordingstoragelimit1.xsd">
      <GeneralSuccess />
    </StorageLimitsResponse>

    Supported elements, attributes and values:

    ElementDescription
    StorageLimitsResponseContains the response. For information about XML schema versions, see XML schemas.
    GeneralSuccessSuccessful request.

    General error response

    General error response from Recording storage limit API.

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" encoding="utf-8"?>
    <StorageLimitsResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SchemaVersion="1.0" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/recordingstoragelimit1.xsd">
      <GeneralError>
        <ErrorCode>[error code]</ErrorCode>
        <ErrorDescription>[description]</ErrorDescription>
      </GeneralError>
    </StorageLimitsResponse>

    Supported elements, attributes and values:

    ElementDescription
    StorageLimitsResponseContains the response. For information about XML schema versions, see XML schemas.
    GeneralErrorError.
    ErrorCodeA numeric error code. See table below.
    ErrorDescriptionDescription of the error.
    Error codeDescriptionCGI
    10Error while processing the request.All
    20Invalid request.All
    40 Specified version is not supported.All
    110Disk not found.

    getlimit.cgi

    setlimit.cgi

    120Invalid size value.setlimit.cgi
    130Supplied size is less than the minimum allowed limit.setlimit.cgi

    Recording API

    Description

    The Recording API is used for recording management. Recordings can be listed, played, stopped and removed. Continuous recordings can be started and stopped. Each recording is identified by a unique Recording ID.

    Recordings are stored on disks, for example SD cards and network shares. Disks are handled by the Disk Management API, see Disk management API.

    The Recording API is used to start and stop continuous recordings. Axis products also support event-triggered and scheduled recordings. These are configured using VAPIX® Event and Action Services, see Event and action services.

    If the Axis product supports continuous recording profiles (parameter Properties.LocalStorage.ContinuousRecording is set to yes), a continuous recording should be configured using addconfiguration.cgi.

    To play recordings, use media.amp from the RTSP API. Using RTSP for playback is recommended because all video formats as well as audio and video synchronization is supported. MJPEG recordings can also be played using play.cgi from the HTTP API.

    The Recording API consists of:

    addconfiguration.cgiAdd continuous recording profile.
    listconfiguration.cgiList continuous recording profile.
    removeconfiguration.cgiRemove continuous recording profile.
    list.cgiSearch for recordings and retrieve information.
    record.cgiStart recording (continuous recording).
    stop.cgiStop active recording.
    remove.cgiRemove recordings.
    play.cgiPlay MJPEG recording. This CGI has been deprecated and will no longer receive updates as of firmware version 10.2.
    RTSP APIPlay H.264, MPEG-4 and MJPEG recordings. See RTSP PLAY.

    Recordings can be exported using the Export Recording API. See Export recording API.

    Date and time format

    The date and time format used in the Recording API is the UTC combined date and time format defined in ISO 8601:

    <yyyy>-<mm>-<dd>T<HH>:<MM>:<SS>Z

    If required, the fraction of a second .<mmmm> can also be used:

    <yyyy>-<mm>-<dd>T<HH>:<MM>:<SS>.<mmmm>Z

    The time offset from UTC can also be included:

    <yyyy>-<mm>-<dd>T<HH>:<MM>:<SS>.<mmmm>±hh:mm

    When using the clock option with the Range header in RTSP requests, the following date and time formats should be used:

    <yyyy><mm><dd>T<HH><MM><SS>[.<mmmm>]Z

    The Range header also supports NPT and SMPTE times, see Play recording using RTSP.

    Prerequisites

    Identification

    Property

    Properties.API.HTTP.Version=3

    Property

    Properties.LocalStorage.LocalStorage=yes

    Firmware

    5.40 and later

    addconfiguration.cgi, removeconfigration.cgi and listconfiguration.cgiin addition require

    Property

    Properties.LocalStorage.ContinuousRecording=yes

    Property

    Properties.LocalStorage.ContinuousRecordingProfiles > 0

    Playback over RTSP requires:

    Property

    Properties.API.RTSP.Version=2.01 and later

    Common examples

    Retrieve a list with information about all recordings.

    http://myserver/axis-cgi/record/list.cgi?recordingid=all

    The response gives a list of all recordings with information about Recording ID, video and audio settings etc (only a part of the response is shown here).

    Response:
    HTTP/1.0 200 OK
    Content-Type: text/xml
       
    <?xml version="1.0" ?>
    <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation=
        "http://www.axis.com/vapix/http_cgi/recording/list1.xsd">
      <recordings totalnumberofrecordings="3" numberofrecordings="3" >
        <recording diskid="NetworkShare" 
          recordingid="20110812_081211_016F_00408C1834FD" ... >
          <video ... />  
          <audio ... /> 
        </recording> 
        <recording diskid="NetworkShare" 
          recordingid="20110813_093530_025B_00408C1834FD" ... >
          <video ... />  
          <audio ... /> 
        </recording> 
        <recording diskid="NetworkShare"
          recordingid="20110813_103530_037C_00408C1834FD" ... >
          <video ... /> 
          <audio ... /> 
        </recording> 
      </recordings> 
    </root>

    Retrieve information about a specific recording.

    http://myserver/axis-cgi/record/list.cgi?
    recordingid=20010115_091153_025B_00408C1834FD

    List the Event IDs associated with recordings on the SD card.

    http://myserver/axis-cgi/record/list.cgi?listentity=eventid&diskid=SD_DISK

    The response shows that recordings with Event IDs motion and audio detection are stored on the SD card.

    Response:
    HTTP/1.0 200 OK
    Content-Type: text/xml
       
    <?xml version="1.0" ?>
    <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation=
        "http://www.axis.com/vapix/http_cgi/recording/list1.xsd">
      <eventids >
        <eventid> motion </eventid>
        <eventid> audio detection </eventid>
      </eventids> 
    </root>

    Play a recording over HTTP.

    http://myserver/axis-cgi/record/play.cgi?
    recordingid=20010115_091153_025B_00408C1834FD

    Remove a recording.

    http://myserver/axis-cgi/record/remove.cgi?
    recordingid=20010115_091153_025B_00408C1834FD

    Add a configuration for continuous recording to the SD card.

    http://myserver/axis-cgi/record/continuous/addconfiguration.cgi?diskid=SD_DISK
    &options=resolution%3D640x480&eventid=continuous_0

    Add a configuration for continuous recording to the network share.

    http://myserver/axis-cgi/record/continuous/addconfiguration.cgi?diskid=NetworkShare
    &eventid=continuous_nas&options=resolution%3D640x480

    Play the continuous recording from 2011–08–12T08:12:11Z to 2011–08–14T10:10:00Z. To make sure that all recorded material from this time period is played, also if the recording was interrupted, the recordings are first listed. The play request is then a loop over the found recordings.

    First, list recordings with eventid=continuous_nas from the desired time period.

    http://myserver/axis-cgi/record/list.cgi?listentity=recordingid
    &eventid=continuous_nas
    &starttime=2011-08-12T08:12:11Z
    &stoptime=2011-08-14T10:10:00Z

    The response below shows that the continuous recording was interrupted twice during the requested time period. A recording can for example be interrupted if the Axis product is restarted or if network connection is lost. The response contains information such as the Recording IDs, start and stop times of the three recordings found during the requested time period. Only a part of the response is shown here.

    Response:
    HTTP/1.0 200 OK
    Content-Type: text/xml
       
    <?xml version="1.0" ?>
    <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation=
        "http://www.axis.com/vapix/http_cgi/recording/list1.xsd">
      <recordings totalnumberofrecordings="6" numberofrecordings="3" >
        <recording diskid="NetworkShare"
          recordingid="20110812_081211_016F_00408C1834FD"
          starttime="2011-08-12T08:12:11Z" 
          stoptime="2011-08-13T09:30:30Z" ... > 
          <video ... />  
          <audio ... /> 
        </recording> 
        <recording diskid="NetworkShare"
          recordingid="20110813_093530_025B_00408C1834FD" 
          starttime="2011-08-13T09:35:30Z" 
          stoptime="2011-08-13T010:30:30Z" ... > 
          <video ... />  
          <audio ... /> 
        </recording> 
        <recording diskid="NetworkShare"
          recordingid="20110813_103530_037C_00408C1834FD" 
          starttime="2011-08-13T010:35:30Z" 
          stoptime="2011-08-14T10:10:00Z" ... > 
          <video ... /> 
          <audio ... /> 
        </recording> 
      </recordings> 
    </root>

    To play the recordings, use the Recording IDs, start times and stop times from the response. The start and stop times are returned in UTC combined date and time format and must be converted before being used in the RTSP Range header. For example, starttime="2011-08-12T08:12:11Z" should be converted to 20110812T081211Z. See Date and time format for more information.

    The play request below is to be inserted in a loop over the recordings from the response; Rec.recordingid is replaced with each of the three returned Recording IDs and Rec.starttime and Rec.stoptime are replaced with the returned start and stop times (converted to the proper time format).

    PLAY rtsp://myserver/axis-media/media.amp?recordingid=Rec.recordingid
    Range: clock=Rec.starttime-Rec.stoptime

    Parameters

    Recording default parameters

    The parameters in the Recording group define default recording settings.

    Recording
    ParameterDefault valueValid valuesAccess controlDescription
    DefaultDiskIdProduct dependentStringadmin: read, write
    operator: read, write
    viewer: read
    Default Disk ID.
    DefaultSplitDuration300Integeradmin: read, write
    operator: read, write
    viewer: read
    The default length (in seconds) of each recording block.

    Add continuous recording profile

    The record/continuous/addconfiguration.cgi is used to configure a continuous recording. The recording will be started when possible.

    An existing recording profile cannot be changed. To change settings, the profile must be removed and replaced with a new recording profile.

    This CGI is available if Properties.LocalStorage.ContinuousRecording=yes and Properties.LocalStorage.ContinuousRecordingProfiles > 0.

    Request

    Access control

    admin, operator

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/record/continuous/addconfiguration.cgi?
    <argument>=<value>[&<argument>=<value>...]

    With the following arguments and values:

    ArgumentValid valuesDescription
    diskid=<string><Disk ID>

    Required.

    The Disk ID of the disk to record to.

    options=<string>Percent-encoded string

    Required.

    Stream options for the recording. Example: streamprofile%3DMyProfile or other image URL settings.

    eventid=<string><Event ID>

    Optional.

    The Event ID classifies the recording. Used with list.cgi to select recordings generated by this continuous recording configuration.

    Default: continuous

    Response

    Responses from record/continuous/addconfiguration.cgi

    Success:

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" ?>
    <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation=
        "http://www.axis.com/vapix/http_cgi/recording/continuousconfigurationadd1.xsd">
      <configure profile="[profile number]" 
             result="OK" />
      ...
    </root>

    Error:

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" ?>
    <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation=
        "http://www.axis.com/vapix/http_cgi/recording/continuousconfigurationadd1.xsd">
      <configure profile="[profile number]"
             result="ERROR" 
             errormsg="[error description]" />
      ...
    </root>

    Supported elements, attributes and values:

    ElementDescriptionAttributeDescription
    configureInformation about the new profile.profileThe profile number.
    resultOK = The configuration was added successfully.
    ERROR = An error occurred while configuring the recording.
    errormsgDescription of the error.

    List continuous recording profiles

    The record/continuous/listconfiguration.cgi is used to list information about continuous recording profiles.

    Request

    Access control

    admin, operator, viewer

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/record/continuous/listconfiguration.cgi?
    <argument>=<value>[&<argument>=<value>...]

    With the following arguments and values:

    ArgumentValid valuesDescription
    profile=<integer>

    Integer

    Optional.
    The continuous recording profile to be listed. If omitted, all profiles will be listed.
    Value of the attribute profile from an Add or List containing continous recording profile responses.

    Response

    Responses from record/continuous/listconfiguration.cgi

    Success:

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" ?>
    <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation=
        "http://www.axis.com/vapix/http_cgi/recording/continuousconfigurationlist1.xsd">
      <continuousrecordingconfigurations>
        <continuousrecordingconfiguration profile="[profile number]"
              diskid="[disk ID]"
              options="[stream options]"
              eventid="[event ID]" />
        ...
      </continuousrecordingconfigurations>
    </root>

    Supported elements, attributes and values:

    ElementDescriptionAttributeDescription
    continuousrecordingconfigurationsContains the listed continuous recording profiles.
    continuousrecordingconfigurationContains information about one continuous recording profile.profileThe profile number.
    diskidThe Disk ID of the disk where the recording is stored.
    optionsThe stream options.
    eventidThe profile’s Event ID.

    Remove continuous recording profile

    The record/continuous/removeconfiguration.cgi is used to stop and remove a continuous recording profile.

    Request

    Access control

    admin, operator

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/record/continuous/removeconfiguration.cgi?
    <argument>=<value>[&<argument>=<value>...]

    With the following arguments and values:

    ArgumentValid valuesDescription
    profile=<integer>

    Integer

    Required.
    The continuous recording profile to be removed.
    Value of the attribute profile from an Add or List containing continous recording profile responses.

    Response

    Responses from record/continuous/removeconfiguration.cgi

    Success:

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" ?>
    <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation="
        http://www.axis.com/vapix/http_cgi/recording/continuousconfigurationremove1.xsd">
      <remove profile="[profile number]" 
             result="OK" />
      ...
    </root>

    Error:

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" ?>
    <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation="
        http://www.axis.com/vapix/http_cgi/recording/continuousconfigurationremove1.xsd">
      <remove profile="[profile number]"
             result="ERROR" 
             errormsg="[error description]" />
      ...
    </root>

    Supported elements, attributes and values:

    ElementDescriptionAttributeDescription
    removeInformation about the removed profile.profileThe profile number.
    resultOK = Recording was removed successfully.
    ERROR = An error occurred while removing the recording.
    errormsgDescription of the error.

    List recordings

    The record/list.cgi is used to search for recordings and list information about found recordings.

    Request

    Access control

    admin, operator, viewer

    Method

    GET/POST

    Syntax:
    http://<servername>/axis-cgi/record/list.cgi?<argument>=<value>
    [&<argument>=<value>...]

    With the following arguments and values:

    ArgumentValid valuesDescription
    listentity=<string>recording(1)
    eventid
    source
    Optional.
    recording = List recordings (Default).
    eventid = List all Event IDs used in recordings.
    source = List all sources used for recordings.
    eventid and source can be combined with the diskid argument.
    recordingid=<string>(1)all
    <Recording ID>
    all = List all recordings.
    <Recording ID> = List recording with the specified Recording ID.
    maxnumberofresults=<integer>IntegerOptional.
    Maximum number of recordings returned.
    startatresultnumber=<integer>IntegerOptional.
    Start the returned result on the n:th recording.
    eventid=<string><Event ID>Optional.
    Name of the event that triggered the recording.
    diskid=<string><Disk ID>Optional.
    The Disk ID of the disk to search for recordings on.
    starttime=<time>(1)UTC ISO 8601 combined date and time(2)Optional.
    Include all recordings with any part of it on or after this time and date.
    stoptime=<time>(1)UTC ISO 8601 combined date and time(2)Optional.
    Include all recordings with any part of it on or before this time and date.
    sortorder=<string>ascending
    descending
    Optional.
    ascending = Sort the list in ascending order according to the recording start time.
    descending = Sort the list in descending order according to the recording start time. Default.
    source=<integer>Quad(3)
    <channel number>
    Optional.
    The source of the recording on a multichannel video encoder.
    Quad = The quad stream
    <channel number> = The video channel number (values are product dependent).
    1. One of recordingid,starttime or stoptime is required if listentity=recording
    2. See Date and time format.
    3. Product dependent

    Response

    The response from record/list.cgi depends on the submitted listentity.

    List recording IDs — Success

    The following response is returned if listentity=recordingid.

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" ?>
    <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation=
        "http://www.axis.com/vapix/http_cgi/recording/list1.xsd">
      <recordings totalnumberofrecordings="[the number of recordings in all attached disks]" 
           numberofrecordings="[the number of matched recordings]" >
        <recording  diskid="[Disk ID]"
          recordingid="[Recording ID]" 
          starttime="[UTC start time]" 
          starttimelocal="[Local start time]" 
          stoptime="[UTC stop time or empty string]" 
          stoptimelocal="[Local stop time or empty string]" 
          recordingtype="[Triggered, scheduled or continuous recording]" 
          eventid="[Name of the event that initiated the recording]" 
          eventtrigger="[Software input for the event that initiated the recording]" 
          recordingstatus="[Recording is active or inactive]" 
          source="[Recording source]"> 
          <video mimetype="[video mime type]" 
            source="[video source]" 
            framerate="[frame rate]" 
            resolution="[resolution]" 
            width="[width]" 
            height="[height]" /> 
          <audio mimetype="[audio mime type]" 
            source="[audio source]" 
            bitrate="[bit rate]" 
            samplerate="[sample rate]" />
        </recording> 
      </recordings> 
    </root>

    Supported elements, attributes and values:

    ElementDescriptionAttributeDescription
    recordingsContains the recordings in the response.totalnumberofrecordingsThe number of recordings in all attached disks. If diskid is used, only recordings in that disk is counted.
    numberofrecordingsThe number of matched recordings, without taking into accountstartatresultnumber and maxnumberofresults.
    recordingContains information about the recording.diskidThe Disk ID of the disk on which the recording is stored.
    recordingidThe Recording ID.
    starttimeStart time of the recording (UTC time).
    starttimelocalStart time of the recording (local time).
    stoptimeStop time of the recording (UTC time).
    stoptimelocalStop time of the recording (local time).
    recordingtypeThe type of recording.
    triggered = Triggered recording.
    scheduled = Scheduled recording.
    continuous = Continuous recording.
    eventidName of the event that initiated the recording.
    eventtriggerThe trigger for the event that initiated the recording.
    recordingstatusStatus of the recording.
    recording = Recording in progress.
    completed = Recording finished.
    unknown = Unknown status.
    sourceMultichannel video encoders only. The video channel used for the recording.
    videoContains video stream information.mimetypeVideo mime type.
    sourceVideo source.
    framerateFrame rate.
    resolutionVideo resolution.
    widthImage width in pixels.
    heightImage height in pixels.
    audioContains audio stream information.mimetypeAudio mime type.
    sourceAudio source.
    bitrateBit rate.
    samplerateSample rate.

    List event IDs — Success

    The following response is returned if listentity=eventid.

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" ?>
    <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation=
        "http://www.axis.com/vapix/http_cgi/recording/list1.xsd">
      <eventids>
        <eventid>"[Event name]" </eventid>
        ...
      </eventids> 
    </root>

    Supported elements, attributes and values:

    ElementDescriptionAttributeDescription
    eventidsThe events in the response.
    eventidName of the event.

    List sources — Success

    If listentity=source, the response lists the sources in which recordings were found.

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" ?>
    <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation=
        "http://www.axis.com/vapix/http_cgi/recording/list1.xsd">
      <sources>
        <source>[Source]" </source>
        ...
      </sources> 
    </root>

    Supported elements, attributes and values:

    ElementDescriptionAttributeDescription
    sourcesList of the sources in which recordings were found.
    sourceSource identifier. For multichannel video encoders, the source is the channel number or the quad stream.

    Start recording

    The record/record.cgi is used to start a recording. The recording will start at once and a recording ID will be returned.

    Note
    The recording must be stopped by calling stop.cgi, see Stop recording.

    Request

    Access control

    admin, operator

    Method

    GET

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

    With the following arguments and values:

    ArgumentValid valuesDescription
    diskid=<string><Disk ID>Required.
    The Disk ID of the disk to record to.
    Example: SD_DISK
    options=<string>StringOptional.

    Stream options for the recording. Example: streamprofile%3DMyProfile or other image URL settings. Please note that the system default will be used if no value is specified.

    Response

    Responses from record/record.cgi

    Success:

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" ?>
    <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation=
        "http://www.axis.com/vapix/http_cgi/recording/record1.xsd">
      <record recordingid="[Recording ID]" 
             result="OK" />
      ...
    </root>

    Error:

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" ?>
    <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation=
        "http://www.axis.com/vapix/http_cgi/recording/record1.xsd">
      <record 
             result="ERROR" 
             errormsg="[error description]" />
      ...
    </root>

    Supported elements, attributes and values:

    ElementDescriptionAttributeDescription
    recordInformation about the started recording.recordingidThe Recording ID.
    resultOK = Recording was started successfully.
    ERROR = An error occurred while starting the recording.
    errormsgDescription of the error.

    Stop recording

    The record/stop.cgi is used to stop an active recording.

    Request

    Access control

    admin, operator

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/record/stop.cgi?<argument>=<value>
    [&<argument>=<value>...]

    With the following arguments and values:

    ArgumentValid valuesDescription
    recordingid=<string><Recording ID>Required. Stop recording with the specified Recording ID.

    Response

    Responses from record/stop.cgi

    Success:

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" ?>
    <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation=
        "http://www.axis.com/vapix/http_cgi/recording/stop1.xsd">
      <stop recordingid="[Recording ID]" 
             result="OK" />
      ...
    </root>

    Error:

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" ?>
    <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation=
        "http://www.axis.com/vapix/http_cgi/recording/stop1.xsd">
      <stop recordingid="[Recording ID]" 
             result="ERROR" 
             errormsg="[error description]" />
      ...
    </root>

    Supported elements, attributes and values:

    ElementDescriptionAttributeDescription
    stopInformation about the stopped recording.recordingidThe Recording ID.
    resultOK = Recording was stopped successfully.
    ERROR = An error occurred while stopping the recording.
    errormsgDescription of the error.

    Remove recording

    The record/remove.cgi is used to remove one or more recordings.

    Request

    Access control

    admin, operator

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/record/remove.cgi?<argument>=<value>
    [&<argument>=<value>...]

    With the following arguments and values:

    ArgumentValid valuesDescription
    recordingid=<string>all
    <Recording ID 1>, <Recording ID 2>, ...
    all = remove all recordings.
    Remove recordings with specified Recording IDs.
    diskid=<string><Disk ID>Optional.
    The disk ID to remove recordings from, for example SD_DISK.
    beforetime=<time>UTC ISO 8601 combined date and time(1)Optional.
    Remove all recordings with any part of it on or before this time and date. The whole recording will be removed. Active recordings will be stopped and then removed.
    Cannot be combined with recordingid.
    eventid=<string><Event ID>Optional.
    Remove recordings triggered by the event with this ID. Cannot be combined with recordingid.
    source=<string>StringOptional.
    Remove recordings from this video source. Cannot be combined with recordingid.
    1. See Date and time format.

    Response

    Responses from record/remove.cgi

    Success:

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" ?>
    <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation=
        "http://www.axis.com/vapix/http_cgi/recording/remove1.xsd">
      <remove recordingid="[Recording ID]" 
             result="OK" />
      ...
    </root>

    Error:

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" ?>
    <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation=
        "http://www.axis.com/vapix/http_cgi/recording/remove1.xsd">
      <remove recordingid="[Recording ID]" 
             result="ERROR" 
             errormsg="[error description]" />
      ...
    </root>

    Supported elements, attributes and values:

    ElementDescriptionAttributeDescription
    removeInformation about the removed recording.recordingidThe Recording ID.
    resultOK = recording was removed successfully.
    ERROR = an error occurred while removing the recording.
    errormsgDescription of the error.

    Play recording

    Note
    The record/play.cgi has been deprecated and will no longer receive updates.

    The record/play.cgi is used to play a MJPEG recording as a stream. The format will be the same as the live view stream.

    Note
    Only MJPEG recordings can be played using this method. H.264 and MPEG-4 recordings must be played using RTSP, see Play recording using RTSP.
    If possible, use the RTSP playback method. RTSP supports all video formats and synchronization of video and audio.

    Request

    Access control

    admin, operator, viewer

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/record/play.cgi?<argument>=<value>
    [&<argument>=<value>...]

    With the following arguments and values:

    ArgumentValid valuesDescription
    recordingid=<string><Recording ID>Required. Play recording with the specified Recording ID.
    mediatype=<string>video
    audio
    Optional. Default: video
    video = play video
    audio = play audio
    rate=<string>max
    numerator/denominator
    Optional.
    The playback rate.
    max = Play as fast as possible. This is useful when an external monitoring application wants to retrieve stored recordings as fast as possible.
    numerator/denominator = Specifies the playback rate as a fraction of the original rate. 1/1 means the original rate. 1/2 means half the original rate. 2/1 means double the original rate.
    Minimum: 1/1000
    Maximum: 1000/1
    starttime=<time>UTC ISO 8601 combined date and time(1)Optional
    Playback start time. Playback will start at the frame closest to this time. If not specified, recording is played from the beginning.
    stoptime=<time>UTC ISO 8601 combined date and time(1)Optional
    Playback stop time. Playback will stop at the frame closest to this time. If not specified, the recording is played to the end.
    1. See Date and time format.

    Play recording using RTSP

    Recordings in all media formats, with video and audio synchronization, can be played using the RTSP API.

    Note
    When playing MJPEG , the maximum resolution is 2040x2040.

    Request

    Access control

    admin, operator, viewer

    Syntax:
    PLAY rtsp://<servername>/axis-media/media.amp?<parameter>=<value>
    [&<parameter>=<value>...]
    Headerfield1: val1<CRLF>
    Headerfield2: val2<CRLF>
    Range: [npt|clock|smpte]=<starttime>-<stoptime><CRLF>
    ...
    <CRLF>
     
    [Body]

    With the following RTSP parameters values:

    RTSP parameterValid valuesDescription
    recordingid=<string><Recording ID>Required.
    Play the recording with the specified Recording ID.
    pull=<bool>0
    1
    Optional.
    1 = Stream as fast as possible. Because the receiving part determines the transfer rate, this is only useful when tunneling RTSP over HTTP.
    0 = Disabled. Default.

    The following additional header field is accepted when playing a recording:

    Header fieldDescription
    Range: [npt|clock|smpte]=<starttime>- <stoptime>

    Play recording from starttime to stoptime. stoptime is optional.

    npt = Normal Play Time. The starttime and stoptime times are relative to the start of the recording.

    clock = Absolute time. starttime and stoptime are UTC ISO 8601 combined date and time strings. See Date and time format.

    smpte = SMPTE (Society of Motion Pictures and Television Engineers) timestamps relative to the start of the recording. starttime and stoptime are SMPTE timecodes.

    Refer to RFC 2326 for details.

    Note
    Refer to the RTSP API for additional header fields and RTSP parameters.

    Export recording API

    Description

    VAPIX® Export recording API is used to export an edge storage recording to a single playable file. It is possible to export a complete recording or to export a part of a recording (a video clip). The exported recording is a Matroska (.mkv) file and can be exported in an encrypted ZIP archive.

    Supported functionality:

    • Retrieve supported capabilities.

    • Retrieve recording export properties such as start time, stop time and estimated file size. Recording export properties should be retrieved before exporting the recording.

    • Export recording.

    Identification

    VAPIX® Export recording API is supported if

    Property

    Properties.LocalStorage.ExportRecording=yes

    Firmware

    5.60 and later

    • API version 1.1 onwards supports a method to export recordings to an external disk (e.g. USB).

    • API version 1.2 onwards supports a method to export encrypted recordings. 256–bit AES ZIP archive encryption is currently supported.

    Common examples

    Get supported XML schema versions

    Use this example to retrieve a list of supported XML schema versions.

    Request:
    http://<servername>/axis-cgi/record/export/schemaversions.cgi
    Response:
    HTTP/1.0 200 OK
    Content-Type: text/xml
     
    <?xml version="1.0" encoding="utf-8"?>
    <ExportRecordingResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SchemaVersion="1.2" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/exportrecording1.xsd">
      <SchemaVersionsSuccess>
        <SchemaVersion>
          <VersionNumber>1.0</VersionNumber>
          <Deprecated>false</Deprecated>
        </SchemaVersion>
        <SchemaVersion>
          <VersionNumber>1.1</VersionNumber>
          <Deprecated>false</Deprecated>
        </SchemaVersion>
        <SchemaVersion>
          <VersionNumber>1.2</VersionNumber>
          <Deprecated>false</Deprecated>
        </SchemaVersion>
      </SchemaVersionsSuccess>
    </ExportRecordingResponse>

    Get export capabilities

    Use this example to retrieve export recording capabilities. The response shows that recordings can be exported as Matroska files.

    Request:
    http://<servername>/axis-cgi/record/export/capabilities.cgi?schemaversion=1
    Response:
    HTTP/1.0 200 OK
    Content-Type: text/xml
     
    <?xml version="1.0" encoding="utf-8"?>
    <ExportRecordingResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SchemaVersion="1.2" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/exportrecording1.xsd">
      <CapabilitiesSuccess>
        <ExportCapabilities ExportFormat="matroska">
          <ExportEncryption EncryptionFormat="zip-aes256"/>
        </ExportCapabilities>
      </CapabilitiesSuccess>
    </ExportRecordingResponse>

    Get Recording ID

    Use this example to retrieve the Recording ID. Use record/list.cgi from the Recording API. See Recording API.

    Request:
    http://<servername>/axis-cgi/record/list.cgi?recordingid=all

    The response shows the Recording ID and information such as recording start time and stop time. Only a part of the response is shown here. For details, see List recordings.

    Response:
    HTTP/1.0 200 OK
    Content-Type: text/xml
     
    <?xml version="1.0" encoding="utf-8"?>
    <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation= "http://www.axis.com/vapix/http_cgi/recording/list1.xsd">
      <recordings totalnumberofrecordings="30" numberofrecordings="30" >
        <recording diskid="SD_DISK" recordingid="20141211_091153_025B_00408CCAD5D78" ... >
          <video ... />
          <audio ... />
        </recording>
        ...
      <recordings>
    </root>

    Get recording export properties

    Use these examples to retrieve recording export properties. Export properties include the recording’s start time, stop time and an estimated file size. Clients should always request recording export properties before exporting a recording.

    Retrieve information about a recording

    To retrieve export properties for a complete recording, specify the Recording ID and the Disk ID:

    Request:
    http://<servername>/axis-cgi/record/export/properties.cgi?schemaversion=1
    &recordingid=20141211_091153_025B_00408CCAD5D78&diskid=SD_DISK
    Response:
    HTTP/1.0 200 OK
    Content-Type: text/xml
     
    <?xml version="1.0" encoding="utf-8"?>
    <ExportRecordingResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SchemaVersion="1.1" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/exportrecording1.xsd">
      <PropertiesSuccess>
        <ExportProperties RecordingId="20141211_091153_025B_00408CCAD5D78" ExportFormat="matroska" EstimatedFileSize="1234" Starttime="2014-12-11T09:11:52Z" Stoptime="2014-12-11T11:00:46Z"/>
      </PropertiesSuccess>
    </ExportRecordingResponse>

    Retrieve information about a recording between a time interval

    To retrieve export properties for a part of a recording, specify the start and stop times.

    In this example, the complete recording’s start time is 2014-12-11 09:11:53 and the stop time is 2014-12-11 11:00:46. The part of the recording to be exported has start time 2014-12-11 09:45:11 and stop time 2014-12-11 10:10:00. These are the start and stop times specified in the export properties request.

    Request:
    http://<servername>/axis-cgi/record/export/properties.cgi?schemaversion=1
    &recordingid=20141211_091153_025B_00408CCAD5D78&diskid=SD_DISK
    &starttime=2014-12-11T09:45:11Z&stoptime=2014-12-11T10:10:00Z

    The response shows that the recording’s proper start time is 09:45:09. The proper start time is the preceding key frame that is closest to the start time specified in the request. Make sure to use the proper start time when exporting the recording.

    Response:
    HTTP/1.0 200 OK
    Content-Type: text/xml
     
    <?xml version="1.0" encoding="utf-8"?>
    <ExportRecordingResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SchemaVersion="1.1" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/exportrecording1.xsd">
      <PropertiesSuccess>
        <ExportProperties RecordingId="20141211_091153_025B_00408CCAD5D78" ExportFormat="matroska" EstimatedFileSize="1234" Starttime="2014-12-11T09:45:09Z" Stoptime="2014-12-11T10:10:00Z"/>
      </PropertiesSuccess>
    </ExportRecordingResponse>

    Retrieve information about a recording encrypted with 256–bit AES

    Request
    http://<servername/axis-cgi/record/export/properties.cgi?schemaversion=1&recordingid=20121211_091153_025B_00408CCAD5D78&diskid=SD_DISK&encryptionformat=zip-aes256
    Response
    <?xml version="1.0" encoding="utf-8"?>
    <ExportRecordingResponse SchemaVersion="1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/exportrecording1.xsd">
      <PropertiesSuccess>
        <ExportProperties RecordingId="20121211_091153_025B_00408CCAD5D78" ExportFormat="matroska" EncryptionFormat="zip-aes256" EstimatedFileSize="1234" Starttime="2012-12-11T09:11:52Z" Stoptime="2012-12-11T10:10:00Z"/>
      </PropertiesSuccess>
    </ExportRecordingResponse>

    Export the recording

    Use the following examples to export a complete or parts of a recording.

    Export a complete recording

    To export a complete recording, specify the Recording ID, the Disk ID and the export format:

    Request:
    http://<servername>/axis-cgi/record/export/exportrecording.cgi?schemaversion=1
    &recordingid=20141211_091153_025B_00408CCAD5D78&diskid=SD_DISK
    &exportformat=matroska
    Response:
    HTTP/1.0 200 OK
    Content-Disposition: attachment; filename="20141211_0911531234_20141211_1234565678.mkv"
    Content-Type: video/x-matroska
     
    <file data>

    Export part of a recording

    To export a part of a recording, specify the start and stop times retrieved in the response from record/export/properties.cgi.

    Request:
    http://<servername>/axis-cgi/record/export/exportrecording.cgi?schemaversion=1
    &recordingid=20141211_091153_025B_00408CCAD5D78&diskid=SD_DISK
    &exportformat=matroska
    &starttime=2014-12-11T09:45:09Z&stoptime=2014-12-11T10:10:00Z
    Response:
    HTTP/1.0 200 OK
    Content-Disposition: attachment; filename="20141211_0945091234_20141211_1010565678.mkv"
    Content-Type: video/x-matroska
     
    <file data>

    Export a recording

    To export a recording, specify the Recording ID, the Disk ID, the export format and the start and stop times.

    Request:
    http://<servername/axis-cgi/record/export/exportrecording.cgi?schemaversion=1&recordingid=20121211_091153_025B_00408CCAD5D78&diskid=SD_DISK&exportformat=matroska&starttime=2012-12-11T09:45:09Z&stoptime=2012-12-11T10:10:00Z
    Response:
    HTTP/1.0 200 OK
    Content-disposition: attachment; filename="20121211_0945091234_20121211_1010005678.mkv"
    Content-Type: video/x-matroska
    
    <file data>

    Export an ongoing recording

    Export an ongoing recording. In this example, the recording’s start time is 2014-12-11 12:11:53 and the recording is exported at 2014-12-12 14:15:43. The exported file contains video from the start time to the export time 2014-12-12 14:15:43.

    Request:
    http://<servername>/axis-cgi/record/export/exportrecording.cgi?schemaversion=1
    &recordingid=20141211_121153_025B_00408CCAD5D78&diskid=SD_DISK
    &exportformat=matroska
    Response:
    HTTP/1.0 200 OK
    Content-disposition: attachment; filename="20141211_1211531234_20141212_1415435678.mkv"
    Content-Type: video/x-matroska
     
    <file data>

    Export a complete recording and specify the file name

    Specify the file name when exporting a recording. The file extension is added automatically.

    Request:
    http://<servername>/axis-cgi/record/export/exportrecording.cgi?schemaversion=1
    &recordingid=20141211_121153_025B_00408CCAD5D78&diskid=SD_DISK
    &exportformat=matroska&filename=my_file
    Response:
    HTTP/1.0 200 OK
    Content-disposition: attachment; filename="my_file.mkv"
    Content-Type: video/x-matroska
     
    <file data>

    Export a recording in a ZIP archive encrypted with 256–bit AES

    To export a recording as a ZIP-file you must use the following request:

    Request
    http://<servername>/axis-cgi/record/export/exportrecording.cgi?schemaversion=1&recordingid=20121211_091153_025B_00408CCAD5D78&diskid=SD_DISK&exportformat=matroska&password=pass_1&encryptionformat=zip-aes256&filename=encrypted_video
    Response
    HTTP/1.0 200 OK
    Content-disposition: attachment; filename="encrypted_video.zip"
    Content-Type: application/zip
    
    <ZIP file data>

    Export part of a recording to USB

    1. Start exporting the recording using exporttoexternal.cgi.

    Request:
    http://<servername/axis-cgi/record/export/exporttoexternal.cgi?schemaversion=1&recordingid=20121211_091153_025B_00408CCAD5D78&diskid=SD_DISK&exportformat=matroska&starttime=2012-12-11T09:45:09Z&stoptime=2012-12-11T10:10:00Z&externaldiskid=USB_DISK&filepath=video.mkv
    Response:
    <?xml version="1.0" encoding="utf-8"?>
    <ExportRecordingResponse SchemaVersion="1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/exportrecording1.xsd">
      <ExportToExternalSuccess>
        <ExportToExternal JobId="1" FilePath="video.mkv"/>
      </ExportToExternalSuccess>
    </ExportRecordingResponse>

    2. Check the progress.

    Request:
    http://<servername/axis-cgi/record/export/getjobstatus.cgi?schemaversion=1&jobid=1
    Response:
    <?xml version="1.0" encoding="utf-8"?>
    <ExportRecordingResponse SchemaVersion="1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/exportrecording1.xsd">
      <GetJobStatusSuccess>
        <JobStatus Status="In Progress" Progress="45"/>
      </GetJobStatusSuccess>
    </ExportRecordingResponse>

    API specification

    Get schema versions

    Use record/export/schemaversions.cgi to retrieve the supported XML schema versions.

    Request

    Access control

    admin, operator, viewer

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/record/export/schemaversions.cgi

    This CGI has no arguments

    Response

    Responses from record/export/schemaversions.cgi

    Success

    A successful request returns the supported schema versions.

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" encoding="utf-8"?>
    <ExportRecordingResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SchemaVersion="1.1" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/exportrecording1.xsd">
      <SchemaVersionsSuccess>
        <SchemaVersion>
          <VersionNumber>[major.minor]</VersionNumber>
          <Deprecated>[true/false]</Deprecated>
        </SchemaVersion>
        <SchemaVersion>
          <VersionNumber>[major.minor]</VersionNumber>
          <Deprecated>[true/false]</Deprecated>
        </SchemaVersion>
          [...]
      </SchemaVersionsSuccess>
    </ExportRecordingResponse>

    Supported elements, attributes and values:

    ElementDescription
    ExportRecordingResponseContains the response. For information about XML schema versions, see XML schemas.
    SchemaVersionsSuccessSuccessful request.
    SchemaVersionContains one schema version.
    VersionNumber

    Schema version. See XML schemas.

    Deprecated

    If true, this version of the XML Schema is deprecated and should not be used.

    Error

    If an error occurred, a GeneralError response is returned. See General error response.

    Error codes: 10, 20, 40

    Get capabilities

    Use record/export/capabilities.cgi to retrieve capabilities supported by the Export Recording API.

    Request

    Access control

    admin, operator, viewer

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/record/export/capabilities.cgi?<argument>=<value>

    with the following arguments and values:

    ArgumentValid valuesDescription
    schemaversion=<integer>Integer

    Required. The major version of the XML Schema to use for the response. See XML schemas.

    Response

    Responses from record/export/capabilities.cgi

    Success

    A successful request returns supported capabilities.

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" encoding="utf-8"?>
    <ExportRecordingResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SchemaVersion="1.1" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/exportrecording1.xsd">
      <CapabilitiesSuccess>
        <ExportCapabilities ExportFormat="[Format 1]"/>
        <ExportCapabilities ExportFormat="[Format 2]"/>
        ...
      </CapabilitiesSuccess>
    </ExportRecordingResponse>

    Supported elements, attributes and values:

    ElementDescriptionAttributeDescription
    ExportRecordingResponseContains the response. For information about XML schema versions, see XML schemas.
    CapabilitiesSuccessSuccessful request.
    ExportCapabilitiesContains one Export Recording API capability.ExportFormat

    Supported media format.

    Error

    If an error occurred, a GeneralError response is returned. See General error response.

    Error codes: 10, 20, 40

    Get export properties

    Use record/export/properties.cgi to retrieve recording export properties. Export properties include the recording’s start time, stop time and an estimated file size. The start time in the response is the proper start time, that is, the preceding key frame that is closest to the requested start time.

    Clients should always request recording properties before exporting a recording.

    To retrieve properties from a specific time interval, specify the start and stop times in the request.

    Request

    Access control

    admin, operator, viewer

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/record/export/properties.cgi?<argument>=<value>&[<argument>=<value>...]

    with the following arguments and values:

    ArgumentValid valuesDescription
    schemaversion=<integer>Integer

    Required. The major version of the XML Schema to use for the response. See XML schemas.

    recordingid=<string>String

    Required. The recording’s Recording ID.

    diskid=<string>String

    Required. Disk ID of the disk where the recording is stored.

    starttime=<time>UTC ISO 8601 combined date and time(1)

    Optional. Start time. Use if retrieving recording export properties for a part of a recording.

    If omitted, start time is set to the recording’s beginning.

    stoptime=<time>UTC ISO 8601 combined date and time(1)

    Optional. Stop time. Use if retrieving recording export properties for a part of a recording.

    Ongoing recordings: If stoptime is omitted, stop time is set to the time the request is sent.

    Finished recordings: If stoptime is omitted, stop time is set to the recording end time.

    exportformat=<string>String

    Optional. The media format that the recording should be exported to.

    encryptionformat=<string>String

    Optional. Specifies the encryption format of the recording.

    1. See Date and time format.

    Response

    Responses from record/export/properties.cgi

    Success

    A successful request returns information about the recordings.

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" encoding="utf-8"?>
    <ExportRecordingResponse SchemaVersion="1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/exportrecording1.xsd">
      <PropertiesSuccess>
        <ExportProperties RecordingId="[Recording ID]" ExportFormat="[Format]" EncryptionFormat="[Encryption format]" EstimatedFileSize="[File size]" Starttime="[Start time]" Stoptime="[Stop time]"/>
      </PropertiesSuccess>
    </ExportRecordingResponse>

    Supported elements, attributes and values:

    ElementDescriptionAttributeDescription
    ExportRecordingResponseContains the response. For information about XML schema versions, see XML schemas.
    PropertiesSuccessSuccessful request.
    ExportPropertiesContains information about one recording.RecordingId

    Recording ID.

    ExportFormat

    Media format.

    EncryptionFormat

    Encryption format.

    EstimatedFileSize

    Estimated file size. Unit: kilobytes

    If the file size cannot be estimated, the size is set to -1.

    Starttime

    Recording start time.

    The returned start time is set to the preceding key frame that is closest to the start time in the request.

    Stoptime

    Recording stop time.

    Error

    If an error occurred, a GeneralError response is returned. See General error response.

    Error codes: 10, 20, 40, 110, 120, 130, 140, 150, 160, 170, 180

    Export recording

    Use record/export/exportrecording.cgi to export a recording. To only export a part of a recording, specify the start and stop times.

    The recording is exported as a single playable file in the specified export format, for example Matroska. If no file name is specified, the file is given a default name constructed from the recording’s start and stop times.

    Request

    Access control

    admin, operator, viewer

    Method

    GET

    Syntax:
    http://<servername>/axis-cgi/record/export/exportrecording.cgi?<argument>=<value>&[<argument>=<value>...]

    with the following arguments and values:

    ArgumentValid valuesDescription
    schemaversion=<integer>Integer

    Required. The major version of the XML Schema to use for the response. See XML schemas.

    recordingid=<string>String

    Required. Recording ID of the recording to export

    diskid=<string>String

    Required. Disk ID of the disk where the recording is stored.

    exportformat=<string>String

    Required. Media format to export the recording to. Use record/export/properties.cgi to retrieve supported media formats.

    starttime=<time>UTC ISO 8601 combined date and time(1)

    Optional. Start time. Use if exporting a part of a recording.

    The start time should match a key frame; use the start time from the response from record/export/properties.cgi.

    If start time does not match a key frame, the start time is set to the closest preceding key frame. If the set start time is outside the recording, a best effort response is returned.

    If starttime is omitted, start time is set to the recording’s beginning.

    stoptime=<time>UTC ISO 8601 combined date and time(1)

    Optional. Stop time. Use if exporting a part of a recording.

    Ongoing recordings: If stoptime is omitted, stop time is set to the time the export recording request is sent.

    Finished recordings: If stoptime is omitted, stop time is set to the recording end time.

    If the set stop time is outside the recording, a best effort response is returned.

    filename=<string>String

    Optional. Name of the exported file. The name must be UTF-8 encoded. File extension will be added automatically and should not be specified.

    password=<string>String

    Optional. Specifies if the exported file should be password protected. It is recommended to not have a password exceed 99 characters, as some applications may not be able to run it. Maximum length is 512 bytes.

    encryptionformat=<string>String

    Required if a password has been set and also specifies the encryption format. Please note that a password must be set before you can use encryptionformat.

    1. See Date and time format.

    Response

    Responses from record/export/exportrecording.cgi

    Success

    A successful request returns the exported recording as a single playable file. If filename was specified in the request, the file is named accordingly. If filename was not specified, the file is given a default name. The default name is constructed using the exported recording’s start and stop times. Start time is set to the preceding key frame that is closest to the requested start time. Stop time is the requested stop time or the end of the recording. If a password has been set the file will be encrypted according to the encryption format. Recordings encrypted in a ZIP archive and without a specified file name will receive a randomized name in the format XXXXXX.zip.

    Success Matroska

    HTTP code

    200 OK

    Content-disposition

    attachment; filename="YYYYMMDD_HHMMSS_YYYYMMDD_HHMMSS.mkv"

    Content-Type

    video/x-matroska

    Body:
    HTTP/1.0 200 OK
    Content-disposition: attachment; filename="20121219_123456_20121220_123456.mkv"
    Content-Type: video/x-matroska
    
    <file data>

    Success ZIP archive

    HTTP code

    200 OK

    Content-disposition

    attachment; filename="XXXXXX.zip"

    Content-Type

    application/zip

    Body:
    HTTP/1.0 200 OK
    Content-disposition: attachment; filename="XXXXXX.zip"
    Content-Type: application/zip
    
    <file data>

    Export a recording to an external disk

    Available from version 1.1.

    Export the recording to an external disk (e.g. USB). It is not possible to run several export-to-external simultaneously.

    Request

    Access control

    viewer

    Method

    GET

    Syntax
    http://<servername/axis-cgi/record/export/exporttoexternal.cgi?<argument>=<value>
    ArgumentValid valuesDescription
    schemaversion=<integer>Integer

    Required. The major version of the XML Schema to use for the response.

    recordingid=<string>String

    Required. Recording ID of the recording to export.

    diskid=<string>String

    Required. Disk ID of the disk where the recording is stored.

    externaldiskid=<string>String

    Required. Specifies the disk the recording should be exported to. Allowed values are USB_DISK.

    exportformat=<string>String

    Required. Media format to export the recording to. Use record/export/properties.cgi to retrieve supported media formats.

    starttime=<time>UTC ISO 8601 combined data and time(1)

    Optional. Start time. Use if exporting a port of a recording.

    The start time should match a key frame; use the start time from the response from record/export/properties.cgi.

    If start time does not match a key frame, the start time is set to the closest preceding key frame. If the set start time is outside the recording, a best effort response is returned.

    If starttime is omitted, start time is set to the recording’s beginning.

    stoptime=<time>UTC ISO 8601 combined data and time(1)

    Optional. Stop time. Use if exporting a part of a recording.

    Ongoing recordings: If stoptime is omitted, stop time is set to the time the export recording request is sent.

    Finished recordings: If stoptime is omitted, stop time is set to the recording end time.

    filepath=<string>String

    Optional. Specifies where the exported recording will be saved and what file name it will get. Any missing directories in the path will be created. If no file path is specified, a default file name will be used and the exported recording is saved to the root of the external disk. No .. are allowed in the path.

    password=<string>String

    Optional. Specifies if the exported file should be password protected. It is recommended to not have a password exceed 99 characters, as some applications may not be able to run it. Maximum length is 512 bytes.

    encryptionformat=<string>String

    Required if a password has been set and also specifies the encryption format. Please note that a password must be set before you can use encryptionformat.

    1. See Date and time format.

    Response

    Returns a job ID that can be used to track the status of the export.

    Success

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" encoding="utf-8"?>
    <ExportRecordingResponse SchemaVersion="1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/exportrecording1.xsd">
      <ExportToExternalSuccess>
        <ExportToExternal JobId="[jobid1]" FilePath="[filepath1]"/>
      </ExportToExternalSuccess>
    </ExportRecordingResponse>

    Error

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" encoding="utf-8"?>
    <ExportRecordingResponse SchemaVersion="1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/exportrecording1.xsd">
      <GeneralError>
        <ErrorCode>[code]</ErrorCode>
        <ErrorDescription>[description]</ErrorDescription>
      </GeneralError>
    </ExportRecordingResponse>

    Get job status

    Available from version 1.1.

    Request to query the job status of a specified job.

    Request

    Access control

    viewer

    Method

    GET

    Syntax
    http://<servername/axis-cgi/record/export/getjobstatus.cgi?<argument>=<value>
    ArgumentValid valuesDescription
    schemaversion=<integer>Integer

    Required. The major version of the XML Schema to use for the response.

    jobid=<integer>Integer

    Required. Specifies the job that the status should be returned for.

    Responses

    Returns the job status. It is possible to receive the job status for all ongoing jobs and the last five completed ones.

    Success

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:

    For ongoing and successfully completed jobs:

    Status can be either In Progress or Done, while Progress is an integer with a value between 0–100 (or -1 if the progress is unknown).

    <?xml version="1.0" encoding="utf-8"?>
    <ExportRecordingResponse SchemaVersion="1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/exportrecording1.xsd">
      <GetJobStatusSuccess>
        <JobStatus Status="[status]" Progress="[progress]"/>
      </GetJobStatusSuccess>
    </ExportRecordingResponse>

    For failed jobs:

    <?xml version="1.0" encoding="utf-8"?>
    <ExportRecordingResponse SchemaVersion="1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/exportrecording1.xsd">
      <GetJobStatusSuccess>
        <GeneralError>
          <ErrorCode>[code]</ErrorCode>
          <ErrorDescription>[description]</ErrorDescription>
        </GeneralError>
      </GetJobStatusSuccess>
    </ExportRecordingResponse>

    Error

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" encoding="utf-8"?>
    <ExportRecordingResponse SchemaVersion="1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/exportrecording1.xsd">
      <GeneralError>
        <ErrorCode>[code]</ErrorCode>
        <ErrorDescription>[description]</ErrorDescription>
      </GeneralError>
    </ExportRecordingResponse>

    General error response

    General error response from Export recording API.

    HTTP code

    200 OK

    Content-type

    text/xml

    Body:
    <?xml version="1.0" encoding="utf-8"?>
    <ExportRecordingResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SchemaVersion="1.1" xsi:noNamespaceSchemaLocation="http://www.axis.com/vapix/http_cgi/exportrecording1.xsd">
      <GeneralError>
        <ErrorCode>[error code]</ErrorCode>
        <ErrorDescription>[description]</ErrorDescription>
      </GeneralError>
    </ExportRecordingResponse>

    Supported elements, attributes and values:

    ElementDescription
    ExportRecordingResponseContains the response. For information about XML schema versions, see XML schemas.
    GeneralErrorError.
    ErrorCodeA numeric error code. See table below.
    ErrorDescriptionDescription of the error.
    Error codeDescriptionCGI
    10Error while processing the request.All
    20Invalid request.All
    40 Specified version is not supported.All
    110Recording not found.properties.cgi
    120Invalid start time.properties.cgi
    130Invalid stop time.properties.cgi
    140Invalid start time. The requested start time is after the stop time. properties.cgi
    150Invalid start time. The requested start time is after the recording’s stop time.properties.cgi
    160Invalid stop time. The requested stop time is before the recording’s start time.properties.cgi
    170Invalid export format.properties.cgi
    180Requested export format is not compatible with the media type.properties.cgi
    190Job not found.getjobstatus.cgi
    200Invalid external disk.exporttoexternal.cgi
    210Unusable external disk.exporttoexternal.cgi
    220Maximum number of jobs reached.exporttoexternal.cgi
    230Invalid file path.exporttoexternal.cgi
    240Invalid password.exporttoexternal.cgi
    250Invalid encryption format.properties.cgiexporttoexternal.cgi
    260Password not set.exporttoexternal.cgi
    270Encryption format not set.exporttoexternal.cgi
    280Requested encryption format is not compatible with requested export format.properties.cgi
    exporttoexternal.cgi

    Edge storage events and actions

    Event recording ongoing

    The Recording ongoing event is emitted when there is an ongoing recording to an edge storage device.

    Topic

    Name

    tnsaxis:Storage/tnsaxis:Recording

    Type

    Stateful

    Nice name

    Recording ongoing

    Source instance

    None

    Data instance

    Nice name

    Recording ongoing

    Type

    boolean

    Name

    recording

    isPropertyState

    true

    Event storage disruption detection

    The Storage disruption detection event is true when there is a problem with a storage device.

    The event is emitted with data instance disruption set to true in the following situations: storage is unmounted, storage is mounted in read-only mode, on read/write errors, storage is removed, storage is full, storage is locked.

    The event is emitted with data instance disruption set to false in the following situations: storage is mounted successfully with read/write permissions, a storage that was locked has been unlocked, data has been successfully removed so that the storage is no longer full.

    Use disks/checkdisk.cgi and/or disks/list.cgi to troubleshoot storage problems.

    Topic

    Name

    tnsaxis:Storage/tnsaxis:Disruption

    Type

    Stateful

    Nice name

    Storage Disruption

    Source instance

    Name:

    disk_id

    Type

    string

    Nice name

    Disk

    Data instance

    Nice name

    Storage Disruption

    Type

    boolean

    Name

    disruption

    isPropertyState

    true

    Record video action template

    Use the Record Video action to record video to a storage device, for example an SD card or a network share. For information about how to retrieve recordings, see Recording API.

    This action can be run as:

    • fixed action — video is recorded during a pre-event and post-event time

    • unlimited action — video is recorded during a pre-event time, while the event is running and during a post-event time

    Action ID

    com.axis.action.fixed.recording.storage

    Action ID

    com.axis.action.unlimited.recording.storage

    ParameterValid valuesDescription
    stream_optionsPercent-encoded stringList of stream parameters such as resolution, compression etc. All parameters supported by RTSP and HTTP stream requests can be used. See Parameter specification RTSP URL and Video streaming over HTTP.
    Example: stream_options=resolution%3D640x480%26compression%3D30%26rotation%3D180
    pre_durationUnsigned integerPre-trigger time in milliseconds. Specify the number of milliseconds to include from the time immediately before the event.
    post_durationUnsigned integerPost-trigger time in milliseconds. Specify the number of milliseconds to include from the time immediately after the event.
    storage_idDisk IDDisk ID of the storage device to record to. Use axis-cgi/disks/list.cgi?diskid=all to list the disks supported by the product. For information about storage disks, see Disk management API.

    Recording group video action template

    By using this action along with Recording group allows you to record video to a recording group, for example on an SD card or a network share. This is useful when you want to set up a recording group that with multiple actions creates a single recording, even when two or more actions are active in parallel.

    This action can be run as:

    • unlimited action — video is recorded during a pre-duration time, while the event is running and during a post-duration time.

    Action ID

    com.axis.action.unlimited.recording_group.storage

    ParameterValid valuesDescription
    recording_group_id Recording group IDRecording group ID for the recording group to record to.