API Documentation

irisity alarm filter supports smtp and https as the main ways of connecting to the system we also offer custom integrations and vendor specific handling of certain alarms please follow our getting started docid\ cy5w0lcchhv9zjwuw4zda to prepare the system and set up api keys and smtp credentials use https when possible when possible, configure the alarms to be sent using https input the following http details https endpoint settings url https //in alarmfilter irisity io port 443 api key \<use api key from getting started docid\ cy5w0lcchhv9zjwuw4zda > https camera identification when making the request, add query parameters to identify the camera an example of this could be post https //in alarmfilter irisity io/?c=unique camera id 123 https send images or the clip in the body encode the body of the request as multipart/form data https //datatracker ietf org/doc/html/rfc2388 and send the images or clip camera identification for https when we parse incoming https alarms we try to identify the camera based on the incoming request smtp/email is also supported if https is not supported or you prefer to use smtp, use the following configuration for the smtp server settings email server (smtp) s alarmfilter irisity io username \<use smtp credentials from getting started docid\ cy5w0lcchhv9zjwuw4zda > password \<use smtp credentials from getting started docid\ cy5w0lcchhv9zjwuw4zda > port 587 encryption tls smtp recipient settings to unique camera id 123456\@alarmfilter irisity io from \<any valid email> incoming email alarm parsing each alarm sent to the alarm filter must contain either a short video clip (preferred) or multiple image frames that jointly make up a video sequence from a surveillance camera this video or image sequence will be called video, video clip, and clip, interchangeably the video or separate images should be at least three frames long, preferably 6 10 frames at least three images/frames are required for the filter to detect motion in the video based on the video clip, each incoming alarm video will be classified as either a true alarm or a false alarm for smtp, the video or images are sent as attachments to the email for https, the video or images are sent through the body of the http request true alarms true alarms are alarms that contain human activity , meaning people or vehicles moving false alarms false alarms are other alarms filtering performance you can expect the irisity alarm filter to filter out more than 95% of all incoming false alarms while removing very few true alarms apis the incoming email service will parse incoming emails using one of multiple api providers if no specific api is specific, the generic provider will be used currently, these providers exist for smtp generic hikvision 1 the following providers exist for https generic the details of each api will be detailed in the following sections camera incoming id the main goal of the parsing is to tie each incoming alarm to a unique i ncoming id each camera needs to have a unique i ncoming id depending on the api used and the parameters sent, this unique name will be either assigned (most common) or explicitly set the incoming id will always be calculated for each incoming alarm, and we recommend where possible to set it explicitly examples of setting the incoming camera id explicitly (smtp) to camera 864020\@af irisity io or equivalently id=camera 864020\@alarmfilter irisity io or camera id=camera 864020\@alarmfilter irisity io (https) https //in alarmfilter irisity io?id=camera 86402 or equivalently https //in alarmfilter irisity io?incoming id=camera 86402 parsing it starts with the recipient (to) address the main method of parsing emails starts with the recipient (to) address of the email this is because most surveillance cameras and network equipment have very limited support for user definable data and parameters anywhere else depending on the api used special parsing may be done that uses other fields, such as the email body or attachments the main method of parsing http requests is done by passing in query parameters in the http query request in the documentation below square bracket \[ ] will be used to show template variables and user definable input \[camera incoming id] means that the unique id of that camera is expected, an example provided by a user could be camera 841748 note that the square brackets should be omitted when transforming the templates to the real world specific api parameters are given in the \[key]=\[value] format keys are always transformed to lowercase, meaning casing typically does not matter note for immix users the simplest way to set up cameras for easy integration with immix is to make the incoming camera id match immix's ids immix supports three different identifiers server id ("s number", originating device identifier) s1234 typically used to correlate a group of cameras to a site in immix alarm input id ("a number", alarm input number) a123 typically used to specify alarm details, alarm type, etc the most typical example would be to specify s number and a number some examples using the smtp api to s1234 a12\@alarmfilter irisity io or equivalently id=s1234 a12\@alarmfilter irisity io or incoming id=s1234 a12\@alarmfilter irisity io would send 1234 as the s number and 12 as the a number to immix in the alarm filter system, the incoming camera id parameter would be s1234 a12 and the camera name would be s1234 a12 to s1234\@alarmfilter irisity io would send 1234 as the s number the camera would be named s1234 to s1234 a12\&folder=my site 1\@alarmfilter irisity io would send 1234 as the s number and 12 as the a number to immix in the alarm filter system, the incoming camera id parameter would be s1234 a12 and the camera would be placed in a folder called my site 1 to folder=my site 1\&camera=camera 1 north gate\&incoming id=s1234 a12\@alarmfilter irisity io or shortened f=my site 1\&c=camera 1 north gate\&id=s1234 a12\@af irisity io all parameters are specified explicitly by name would send 1234 as the s number and 12 as the a number to immix in the alarm filter system, the incoming camera id parameter would be s1234 a12 the camera would be in a folder called my site 1 the user facing name of the camera would be camera 1 north gate allowed length, characters, and query string parameters email addresses are limited in the characters they support our parsing is based on a subset of url query strings supported characters are letters ( a–z and a–z ), numbers ( 0–9 ), and the character (hyphen) when (hyphen) is used it will be transformed to (space) when generating user facing names while special character encoding is technically supported, we do not recommend using it character encoding is done using the %hh hexadecimal representation of that character formally, email addresses are bound by the rfc5322 standard ( wikipedia ), which supports query strings however, many devices have additional constraints, see below restrictions for smtp max length 64+63 characters (or just 64 in total) the rfc standard specifies max 64 characters for the user part of an email (before the @) max 63 characters for the domain part of an email (after the @) where an email address is \[user]@\[domain] there are, however, devices that set the total limit to 64 characters lacking support in many cameras and nvrs! due to lacking support in many cameras and other network equipment, we provide a fallback & can be replaced by in all examples below (ampersand replaced by a dot) = can be replaced by in all examples below (equals replaced by underscore) this means that the following two email recipient addresses are equivalent and will be parsed the same way folder=folder 1\&camera=camera 1\@alarmfilter irisity io folder folder 1 camera camera 1\@alarmfilter irisity io shortening the email address the length limit can sometimes be a problem we therefore support shorthands \@alarmfilter irisity io can be replaced by \@af irisity io each parameter listed below has a shorthand api= can be replaced with a= camera= can be replaced with c= folder= can be replaced with f= nvr= can be replaced with n= recipient field format the recipient field takes one of two main formats \[incoming camera id]@alarmfilter irisity io this method is used when the unique incoming id is known \[param1]=\[value1]&\[param2]=\[value2]&\[param3]=\[value3] \@alarmfilter irisity io selecting the right api to select the right api, the api=\[the selected api] parameter is used the shorthand for api= is a= four examples are given below smtp camera 841748\@alarmfilter irisity io https https //in alarmfilter irisity io?camera=camera 841748 no api parameter is given, meaning the generic api is selected smtp api=hikvision 1&\[other parameters]@alarmfilter irisity io the hikvision 1 api is selected smtp a=hikvision 1&\[other parameters]@af irisity io an equivalent shorthand version of the above api=unknown api in cases where the selected api is unknown, the email will be disregarded and the error logged generic api emails are parsed using the generic api unless another is explicitly specified this api gets all information from the email recipient (to) address or the query parameters to the https request the parameters that can be specified are \[incoming camera id] , see above folder=\[deep folder path] to set a folder/site prefix (underscore dash underscore) will be converted to / , meaning subfolder camera=\[camera name] to set the camera name when the camera name is specified it is recommended to also specify a site unique folder to avoid two cameras getting the same incoming camera id either incoming camera id or camera needs to be specified generic api examples example 1 incoming id smtp camera 841748\@alarmfilter irisity io https http //in alarmfilter irisity io?camera=camera 841748 will directly correlate the incoming alarm to the camera with the unique incoming camera id camera 841748 example 2 folders smtp folder=site abc\&camera=camera 123\@alarmfilter irisity io https https //in alarmfilter irisity io?folder=site abc\&camera=camera 123 uses the recommended folder + camera name structure to generate a unique incoming camera id the incoming camera id name will be site abc camera 123 the camera, when created in the system, will be called camera 123 and placed in the folder site abc example 3 folder levels smtp folder=us east connies construction\&camera=camera 12\@alarmfilter irisity io https https //in alarmfilter irisity io?folder=us east connies construction\&camera=camera 12 uses the recommended folder + camera name structure to generate a unique incoming camera id is used to separate two folder levels the incoming camera id will be us east connies construcion camera 12 the camera, when created in the system, will be called camera 12 and placed in the folder tree us east / connies construction example 4 shorthands and replacement characters smtp f us east connies construction c camera 12\@af irisity io https https //in alarmfilter irisity io?f=us east connies construction\&c=camera 12 equivalent to example 3, but with shorthands and replacement characters to support more equipment and to get below 64 characters in length example 5 not recommended smtp camera=camera 14\@alamfilter irisity io https http //in alarmfilter irisity io?camera=camera 14 the above example will generate the unique incoming id using only the camera name, meaning that when another camera 14 is added to the system, the results will be unpredictable hikvision 1 the hikvision 1 has been created to deal with the fact that many hikvision nvrs and dvrs are unable to specify different recipient (to) email addresses for different connected cameras for hikvision nvrs , please use the api documentation docid\ s xm gah1 jisvoadcqbz documentation above it uses the parameters specified by the user, as well as convention based metadata set by hikvision in alarm clip file names and the email body to generate a unique incoming camera id the supported parameters are api=hikvision 1 , required to select the api folder=\[deep folder path] to set a folder/site prefix (underscore dash underscore) will be converted to / , meaning subfolder nvr=\[nvr name] to set the nvr/dvr name when specified it is recommended to also specify a site unique folder to avoid two cameras getting the same incoming camera id examples api=hikvision 1\&folder=site abc\&nvr=nvr 123\@alarmfilter irisity io uses the recommended folder + nvr name structure in combination with hikvision generated metadata to generate a unique incoming camera id the incoming camera id will be similar to site abc nvr 123 a12 for the case when channel 12 triggered the alarm the camera when created in the system, will be named similarly to a12 and placed in the folder site abc api=hikvision 1\&folder=us east connies construction\&nvr=nvr 12\@alarmfilter irisity io uses the recommended folder + nvr name structure in combination with hikvision generated metadata the incoming camera id will be similar to us east connies construction nvr 12 a03 for the case when channel 3 triggered the alarm the camera, when created in the system, will be named similarly to a03 and placed in the folder tree us east / connies construction a hikvision 1 f us east c construction n nvr 12\@af irisity io uses alternates since hikvision devices can be picky with regards to = and & uses shorthands to get under a total length of 64, which is required by some hikvision devices used a shorter folder name, again to get under the 64 character limit (inner most folder name will be c construction instead of connies construction ) api=hikvision 1\&nvr=nvr 14 not recommended will generate the incoming id using only the nvr name and hikvision generated metadata, meaning that when another nvr 14 is added to the system, the results will be unpredictable