NAV
cURL

Introduction

The Eagle Eye Video API is a comprehensive REST based API for recording, indexing, and storing camera video. The Eagle Eye Video API handles all the heavy lifting of interfacing to the cameras, recording video, securely transmitting video to the cloud, storing video, and making video available for use for your applications. All of the Eagle Eye Security Camera VMS user interfaces (web, iOS, Android) have been built using this API.

We have language bindings in cURL. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Getting Started

The Eagle Eye Video API allows you to securely record, manage, and playback video from any camera, any place, any time. A robust annotation interface and smart bandwidth management allows you to turn terabytes of raw video into useful data.

Since the API is based on REST principles, it’s very easy to write and test applications. You can use your browser to access URLs, and you can use many different HTTP clients in nearly any programming language.

Get an API Key

Create Developer Account

To get started with the Eagle Eye Video API you will need an API Key. This is used to identify you and your application. It also makes everything secure. To get an API Key you will need an account (so that you have some place to do some testing). You can either use your existing account or create a Developer Account. You can create an API Key in your existing account under the Account Settings.

You will have to verify your email address to create your Developer Account. You will also get an email with a shortcut to create the API Key. Click on the shortcut link to create your API Key and get started writing some code.

You may also want to purchase a development hardware kit from us (so you can connect some cameras). These are available at a large discount for developers. You can get an Eagle Eye Bridge and even some cameras from us for development and testing. Just email us for more info and pricing.

The API Key should be located in the header under the “Authorization” key with a colon appended to it.

Note user password authentication is still required. Please see the section on Single Sign On for alternatives to password authentication.

Request

curl --cookie "auth_key=[AUTH_KEY]" -X PUT -v -H "Authentication: [API_KEY]:" -H "Authentication: [API_KEY]:" -H "content-type: application/json" https://login.eagleeyenetworks.com/g/user -d '{"first_name": "[FIRST_NAME]", "last_name": "[LAST_NAME]", "email": "[EMAIL]"}'

Json Response

{
    "id": "ca0ffa8c"
}

Visual Steps

alt text alt text alt text alt text alt text

Types

Type Meaning
EENTimestamp Format YYYYMMDDhhmmss.xxx
Coordinated Universal Time
Example Jan 2, 2017 08:30:20.00 == 20170102083020.000

Authentication

Overview

Gaining access to the Eagle Eye API is a two-stage process: Clients first present their credentials and Realm to obtain a single use Authentication Token. This single use token is valid for a pre-defined duration or until it has been used. Once the Authentication Token is obtained the Client must utilize it in an Authorize service call to obtain a session ID (via the “auth_key” Cookie) that provides access to resources. This two phase approach allows Clients to authenticate and operate in multiple domains. The first step is done using Authenticate. The second step is done using Authorize. Note that the Authenticate call must be done over an https connection.

In addition to the simple authentication scheme described above, also a more secure authentication scheme, known as Two Factor Authentication (TFA) may be used. TFA is a method of confirming a user’s claimed identity by utilizing a combination of two different components. The first component is a user’s password and the second is a one-time TFA code delivered to the user via another communication channel - e-mail or a text message sent to the user’s mobile phone.

Whether simple or TFA authentication scheme is used for a particular user’s login is determined by this user’s settings in the system. Note, however, that an account administrator may enforce all users in a particular account to use TFA scheme.

If TFA scheme is in use, the Authorize call will expect the TFA code to be passed in addition to the token obtained from the Authenticate call.

Once the “auth_key” cookie is obtained from the “Authorize” call, there are 2 methods for which you can use the session ID to make subsequent calls to the API. The first, is simply to pass the “auth_key” cookie with all API requests. The second method, is to take the value of the “auth_key” cookie and pass it in the request as the “A” parameter. The “A” parameter can be used with any method (GET, PUT, POST, DELETE). The order of precedence for session ID retrieval is as follows:

  1. “A” parameter in the query string of any method (GET, PUT, POST, DELETE)
  2. “A” parameter in the POST data
  3. “A” parameter in the request body (e.g. PUT)
  4. “auth_key” cookie

All status codes are listed in order of precedence, meaning the first one listed is the one returned if its respective conditions are met, and the last one listed is the one that will be returned if none of the preceding codes’ conditions are met.

Step 1: Authenticate

Request

curl -v --request POST https://login.eagleeyenetworks.com/g/aaa/authenticate --data-urlencode "username=[USERNAME]" --data-urlencode "password=[PASSWORD]"

Json Response, simple authentication

{
  "token": "O3k0hNH3jQgjaxC0bLG9/5cM+Z7eWdPe0c+UpEZNXOs7PTFH45Dr9M3wxLkP6GjcPuCw8lXVTkHGA1zgx/q44HBv3Xmcj4/XzN2f6Hv+mZVIy8LorX8N5a6fNVRknWWW86nCHfbLvOP6TPcmBP1dD10ynnGeAdlQHTqMN5mvKH24WwZgVFbM4DyhyWu+eTN+t1XNROegJdZRjhaYCZ1FVKkdnrlsrMD6JSr/tE7byCLVjPcwzVabA+x0tDbGipystTNYPZyDVr3DQM70SV6kfqg2irlC8/zDu7a2EhI1IQWuZZ2GQIQm5jBtj9UR/p7ainHVhEc/bSFYUCvziepcAa=="
}

Json Response, TFA authentication

{
  "token": "MiDUwMQqwP1JsfKqbqT1DQ8hJFHEOZfROEUtBvnuqv0ICxvcOybkS1n9/awjrJ9YKijb60GqdUDPP8TW4o8Ei8iI8OXC/dj74KC2cLMxJ2vs/hmYPfbW8OpCwf0k683a2LfIbjcC3Uy/SmDpOsxVdPMTXQEGJHXD3ItmAvoQ5MOoRKfHBNOu7OJBWQjPUjeP0fkHSrx8JgAHSqT5SwRM0mLysFmiFHF0h7/5Apt81dDhZwLBDwwSrl+kTqgn+wnw6rJ432liESdK+yp3Qefk1wAtytoTJkkBE2srqsHJdW4ryVYKk9SKA62Cz7pO3VUaD8Yxx9Ff2Os9ez6TdfBmqg==",
  "two_factor_authentication_code":
  {
    "sms": "*** *** 779",
    "email": "***********@gmail.com"
  }
}

Login is a 2 step process when using simple authentication and a 3 step process using TFA scheme.

Simple scheme:
Authenticate, then Authorize with the token returned by Authenticate.

TFA scheme:
Authenticate, Instruct the system to send TFA Code to the user, Authorize with the token received from step 1 and the TFA code received from step 2

HTTP Request

POST https://login.eagleeyenetworks.com/g/aaa/authenticate

Parameter Data Type
username string
password string

HTTP Response

Returned parameters Data Type Description
token string token to be used in Authorize step
two_factor_authentication_code JSON dictionary with two keys:
sms - scrubbed user’s SMS number,
email - scrubbed user’s e-mail address
present in response only if TFA scheme is being used.

NOTE 1:
The validity of token is:

NOTE 2:
For TFA scheme, the system uses the parameter sms_phone of the user’s model (see User Model section). If SMS-based authentication is to be used, that parameter MUST be specified at the user’s creation time (see Create User API Call)* If user’s parameter sms_phone has not been set, the value of the sms key will be No sms phone found.

NOTE 3:
The TFA-related user’s data (i.e. SMS Phone or e-mail), once set at the time of user’s account creation can only be modified by that user alone. Any such modification will also be TFA authenticated. Account Super User may not change such data for security reasons.

Error Status Codes

HTTP Status Code Description
400 Some argument(s) are missing or invalid
401 Supplied credentials are not valid
402 Account is suspended
460 Account is inactive
461 Account is pending
412* User is disabled
462 User is pending. This will be thrown before 401 if username is valid and Account is active.
200 User has been authenticated. Body contains JSON encoded result

* Code 412 is also returned if TFA scheme is used and the user’s account has been locked due to more than 3 failed attempts to authorize with a TFA code.

Step 2: Send TFA Code (only if using TFA Scheme)

Request, simple authentitaction scheme

curl -D - --request POST https://login.eagleeyenetworks.com/g/aaa/two_factor_authenticate --data-urlencode token=[TOKEN] two_factor_authentication_type=sms
curl -D - --request POST https://login.eagleeyenetworks.com/g/aaa/two_factor_authenticate --data-urlencode token=[TOKEN] two_factor_authentication_type=email

This step is only to be executed when TFA scheme is used for the user log in, i.e., if the Authenticate call returned two_factor_authentication_code key in response. Otherwise proceed to step 3: Authorize.

HTTP Request

POST https://login.eagleeyenetworks.com/g/aaa/two_factor_authenticate

Parameter Data Type
token string
token received in step 1
two_factor_authentication_type string
Must be ‘sms’ or 'email’

HTTP Response

This API call does not return data in response.

NOTE 1:
The validity of TFA code sent to the user is 15 minutes.

Response Status Codes

HTTP Status Code Description
400 Some argument(s) are missing or invalid
412 Unable to send TFA code with the TFA authentication type selected
415 Specified TFA authentication type not supported
200 Success, TFA code has been sent to the user

Step 3: Authorize

Request, simple authentitaction scheme

curl -D - --request POST https://login.eagleeyenetworks.com/g/aaa/authorize --data-urlencode token=[TOKEN]

Request, TFA scheme

curl -D - --request POST https://login.eagleeyenetworks.com/g/aaa/authorize --data-urlencode token=[TOKEN] two_factor_authentication_code=[TFA_CODE]

Json Response

{
    "is_sms_include_picture": 0,
    "last_name": "",
    "uid": " ",
    "is_export_video": 1,
    "layouts": [
        "217f0fd4-450f-11e4-a983-ca8312ea370c"
    ],
    "account_map_lines": null,
    "postal_code": null,
    "is_account_superuser": 1,
    "timezone": "US/Pacific",
    "active_brand_subdomain": "c001",
    "sms_phone": null,
    "city": null,
    "first_name": null,
    "user_id": "ca0e1cf2",
    "is_notify_enable": 1,
    "owner_account_id": "00004206",
    "json": "{}",
    "id": "ca0e1cf2",
    "is_superuser": 0,
    "state": null,
    "last_login": "20141006173752.672",
    "is_recorded_video": 1,
    "camera_access": [
        [
            "1005f2ed",
            "r"
        ],
        [
            "100bd708",
            "r"
        ]
    ],
    "notify_period": [
        "0-0000-2359",
        "1-0000-2359",
        "2-0000-2359",
        "3-0000-2359",
        "4-0000-2359",
        "5-0000-2359",
        "6-0000-2359"
    ],
    "email": "john.doe@fakeemail.com",
    "utc_offset": -25200,
    "mobile_phone": null,
    "street": [],
    "notify_rule": [
        "one-email-0"
    ],
    "is_active": 1,
    "is_user_admin": 1,
    "phone": null,
    "is_layout_admin": 1,
    "is_live_video": 1,
    "is_device_admin": 1,
    "is_branded": 1,
    "alternate_email": null,
    "active_account_id": "00004206",
    "access_period": [],
    "is_staff": 0,
    "country": "US",
    "is_master": 0,
    "is_pending": 0


}

Authorize is the final step of the Login process, by using the token from the first step (Authenticate) and - if TFA scheme is used - the TFA code delivered to the user by e-mail or SMS. A Successful Authorize call returns an authorized user object, and sets the 'auth_key’ cookie. For all subsequent API calls, either the cookie can be sent or the value of the cookie can be sent as the 'A’ parameter. When TFA scheme is used, this call will also set tfa_key cookie. See Authorized devices section for more detail on this cookie.

The host url for API calls can originally be done against “https://login.eagleeyenetworks.com”, but after authorization is returned the API should then use the branded subdomain as returned from authorization. As such the branded host url will become “https://[active_brand_subdomain].eagleeyenetworks.com” where the active_brand_subdomain field is returned in the authorization response.

For example after the authorization in the example on the right, the host url should be changed to “https://c001.eagleyenetworks.com”.

Each account will consistently have the same branded subdomain and as such will not change throughout the life of the session. Caching the subdomain is safe to do as long as the client software validates against the active_brand_subdomain after authorization. Using the branded subdomain is important for speed and robustness.

HTTP Request

POST https://login.eagleeyenetworks.com/g/aaa/authorize

Parameter Data Type
token string
two_factor_authentication_code string, 4 decimal digits
Used only for TFA scheme. Not used when authorizing with the simple scheme

NOTE 1:
More than 3 failed attempts to Authorize with TFA code will lock the user’s account. It then can only be unlocked by Eagle Eye’s technical support staff.
When the user’s account has been locked the user is notified of this fact by e-mail.

HTTP Response

When successful, this API call returns JSON data structure corresponding to User Model (see section User Model)

Error Status Codes

When using simple authentication scheme

HTTP Status Code Description
400 Some argument(s) are missing or invalid
401 Invalid Token supplied
200 User has been authorized for access to the realm

When using TFA authentication scheme

HTTP Status Code Description
400 Some argument(s) are missing or invalid
401 Invalid Token supplied, or missing TFA code, or attempting to authorize with expired TFA code
406 Invalid TFA supplied or Invalid TFA and invalid Token supplied
429 This user’s account has been locked due to more than 3 failed attempts to Authorize
200 User has been authorized for access to the realm

Forced vs. Optional TFA scheme

Depending whether the Account to which the user belongs enforces TFA or not, the user may be able to select simple authentication for their future log-ins rather than TFA.
In order to find out whether the account enforces TFA, examine the is_two_factor_authentication_forced flag in the Account record returned by Get Account API Call. This flag can be set or cleared by the Account Super User with the Update Account API call.
If the is_two_factor_authentication_forced is set to 0 the user may switch to simple authentication scheme. That is achieved by clearing is_two_factor_authentication_enabled flag in the User record. This can only be achieved by the user themselves (not e.g. by Account Super User) Update of any TFA-related field in the User record is performed through a dedicated TFA update endpoint /g/aaa/two_factor_authenticate/update. See next section.

TFA Update

Data present in the User record that affects the TFA scheme is security-sensitive and therefore may only be altered using a dedicated endpoint, whose operation is itself TFA protected. This data includes three fields in the User model:

Field Description Remarks
sms_phone Phone number to which text messages (SMS) containing TFA code will be delivered May only be changed when using SMS for TFA code delivery
Code will be delivered to the new phone number
email E-mail address to which messages containing TFA code will be delivered May only be changed when using e-mail for TFA code delivery
Code will be delivered to the new e-mail address
is_two_factor_authentication_enabled 1 - user will be required to authenticate with TFA
0 - user will authenticate with a simple scheme
May be updated with either SMS or e-mail delivery of TFA code

The fields described above may only be changed one at a time.

TFA Update is a two-step process:

1.Request Update

This step initiates the TFA data update process.

HTTP Request

POST https://login.eagleeyenetworks.com/g/aaa/two_factor_authenticate/update

Parameter | Data Type | Description ——— | ———– two_factor_authentication_type | 'sms' or 'email' | Which method to use for TFA code delivery to verify this update request password | string | The user’s password update_json | JSON structure containing the name of the updated field and its new value.
Updated can only be one field at a time | Example:
{
  'sms_phone':'+123456789'
}

HTTP Response

This API call returns no data.

HTTP Status Code Description
400 Some argument(s) are missing or invalid. E.g. update of sms_phone is requested with two_factor_authentication_type set to email or vice versa
401 Invalid user password supplied
415 Invalid TFA code delivery method supplied in two_factor_authentication_type
200 Success, proceed to verification step

2.Verify update request with TFA

HTTP Request

POST https://login.eagleeyenetworks.com/g/aaa/two_factor_authenticate/verify

Parameter | Data Type | Description ——— | ———– two_factor_authentication_code | string, 4 decimal digits | The 4-digit code received via sms or e-mail

HTTP Response

This API call returns no data.

HTTP Status Code Description
400 Some argument(s) are missing or invalid.
406 Invalid TFA code supplied
200 Success

Authorized devices

In order to make the log-in process as convenient as possible for the user, the system will allow for use of the simple authentication scheme on devices used previously by that user for a successful TFA-based log in.
Upon a successful TFA-based log in, the Authorize API call sets a cookie tfa_key in the browser. Subsequent execution of Authenicate API Call with the correct username and password will start of a simple authentication scheme, which can be told by absence of two_factor_authentication_code field in the response of Authenicate. In such case one can skip the Send TFA Code API call and proceed immediately to execute Authorize API Call, as is the process for a non-TFA-enabled user login.

NOTE 1:
The same tfa_key value may be used for multiple users, who have successfully authorized in the past from the particular device.

NOTE 2:
The list of authorized devices for any user is stored in the field user_authenticated_clients in the User record. See User Model section for details.

AAA

Overview

This section is for creating new accounts and the steps to recover an account. If you are creating sub-accounts tied to your current account refer to Account

Create Account

Request

curl --request POST https://login.eagleeyenetworks.com/g/aaa/create_account --data "email=[EMAIL]&password=[PASSWORD]"

This is used to create a new account and the super user for the account. As a part of the creation process, the service sends a confirmation email containing a link (with account id and activation token), which the user must click to activate the account. Account cannot be used until it is activated

HTTP Request

POST https://login.eagleeyenetworks.com/g/aaa/create_account

Parameter Data Type Description Required For
email string Email address POST
password string Password POST
name string Account name
realm string Realm (defaults to current user’s realm)
first_name string User first name
last_name string User last name
timezone string Timezone name (defaults to ‘US/Pacific’)
is_api_access_needed boolean Grant API access to this new account

Error Status Codes

HTTP Status Code Description
400 Unexpected or non-identifiable arguments are supplied
406 Realm is invalid due to not being a root realm
409 Email address has already been registered for the specified realm
202 Account has been created and a confirmation email has been sent to the provided email address

Validate Account

Request

curl --request POST https://login.eagleeyenetworks.com/g/aaa/validate_account --data "id=[ID]&token=[TOKEN]"

Json Response

{
    "user_id": "ca103fea"
}

This is used to verify the email address supplied when the account is created. When successful, the account is set to active and a user session is created. User will not be required to login again

HTTP Request

POST https://login.eagleeyenetworks.com/g/aaa/validate_account

Parameter Data Type Description Required For
id string Account id POST
token string Account validation token POST

HTTP Json Attributes

Parameter Data Type Description
user_id string Unique identifier for validated user

Error Status Codes

HTTP Status Code Description
400 Unexpected or non-identifiable arguments are supplied
402 Account is suspended
406 Information supplied could not be verified
409 Account has already been activated
412 User is disabled
460 Account is inactive
200 User has been authorized for access to the realm

Forgot Password

Request

curl --request POST https://login.eagleeyenetworks.com/g/aaa/forgot_password --data "email=[EMAIL]"

Password recovery is a multi-step process:

HTTP Request

POST https://login.eagleeyenetworks.com/g/aaa/forgot_password

Parameter Data Type Description Required For
email string Email address POST

Error Status Codes

HTTP Status Code Description
400 Unexpected or non-identifiable arguments are supplied
402 Account is suspended
406 Information supplied could not be verified
412 User is disabled
460 Account is inactive
461 Account is pending
462 User is pending
202 A reset email has been sent to the supplied email address. This status will be provided even if the email address was not found. This prevents attacks to discover user accounts

Check Password Reset Token

Request

curl --request POST https://login.eagleeyenetworks.com/g/aaa/check_pw_reset_token --data "token=[TOKEN]"

This is step two of the password recover/reset process. It verifies that the supplied token is a valid reset token

HTTP Request

POST https://login.eagleeyenetworks.com/g/aaa/check_pw_reset_token

Parameter Data Type Description Required For
token string Password reset token provided in email POST

Error Status Codes

HTTP Status Code Description
400 Unexpected or non-identifiable arguments are supplied
402 Account is suspended
406 Token not valid or not found
412 User is disabled
460 Account is inactive
461 Account is pending
202 Token is valid

Reset Password

Request

curl --request POST https://login.eagleeyenetworks.com/g/aaa/reset_password --data "token=[TOKEN]&password=[PASSWORD]"

Json Response

{
    "user_id": "ca0e1cf2"
}

This is step three of the password recover/reset process. It both verifies that the supplied token is a valid reset token and then, if valid resets the password associated with the token to the newly supplied password. Upon completion, a user login session is created

HTTP Request

POST https://login.eagleeyenetworks.com/g/aaa/reset_password

Parameter Data Type Description Required For
token string Password reset token provided in email POST
password string New password POST
accepted_terms_of_service_urls string New terms of service acceptance url

HTTP Json Attributes

Parameter Data Type Description
user_id string Unique identifier for validated user

Error Status Codes

HTTP Status Code Description
400 Unexpected or non-identifiable arguments are supplied
402 Account is suspended
406 Token not valid or not found
412 User is disabled
460 Account is inactive
461 Account is pending
200 User has been authorized for access to the realm

Resend Registration Email

Request

curl --request POST https://login.eagleeyenetworks.com/g/aaa/resend_registration_email --data "email=[EMAIL]"

For users who have registered for an account, but never confirmed the registration. This will allow the registration confirmation email to be re-sent

HTTP Request

POST https://login.eagleeyenetworks.com/g/aaa/resend_registration_email

Parameter Data Type Description Required For
email string Email address of the account contact for a pending account POST
realm string Realm (defaults to current user’s realm)

Error Status Codes

HTTP Status Code Description
400 Unexpected or non-identifiable arguments are supplied
402 Account is suspended
404 Account with this email address and realm could not be found
409 Account is already active (not pending)
412 User is disabled
460 Account is inactive
202 Account was located and verified to be in the pending state. A registration email has been recreated and sent to the provided email address

Resend User Verification Email

Request

curl --request POST https://login.eagleeyenetworks.com/g/aaa/resend_user_verification_email --data "email=[EMAIL]"

For users who have had a user account created, but never confirmed their user account. This will allow the user confirmation email to be re-sent

HTTP Request

POST https://login.eagleeyenetworks.com/g/aaa/resend_user_verification_email

Parameter Data Type Description Required For
email string Email address of the new user POST
realm string Realm (defaults to current user’s realm)

Error Status Codes

HTTP Status Code Description
400 Unexpected or non-identifiable arguments are supplied
402 Account is suspended
404 User with this email address and realm could not be found
409 User is already active (not pending)
412 User is disabled
460 Account is inactive
461 Account is pending
202 User was located and verified to be in the pending state. A verification email has been recreated and sent to the provided email address

Change Password

Request

curl --cookie "auth_key=[AUTH_KEY]&api_key=[API_KEY]" --request POST https://login.eagleeyenetworks.com/g/aaa/change_password --data "password=[PASSWORD]&current_password=[CURRENT_PASSWORD]"

Json Response

{
    "id": "ca02c000"
}

This allows a user to change their password directly while authenticated and also allows super users to change the password of the users they manage:

HTTP Request

POST https://login.eagleeyenetworks.com/g/aaa/change_password

Parameter Data Type Description Required For
id string Id of the user having their password changed. Optional. Defaults to the id of the authenticated user. If empty or equal to authenticated user, then 'current_password’ becomes required
password string New password POST
current_password string Current password of the user. Optional. If 'id’ argument is empty, or is equal to the authenticated user’s id, then this is required

Error Status Codes

HTTP Status Code Description
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
404 User with the 'id’ provided cannot be found
406 The 'current_password’ provided does not match the password of the authenticated user
200 User password was changed successfully

Switch Account

Request

curl --cookie "auth_key=[AUTH_KEY]" --request POST https://login.eagleeyenetworks.com/g/aaa/switch_account

Allows a user to 'log in’ to another account which the they have access to (see 'account/list’). Most commonly this would be needed for a master account user accessing their sub-accounts. Only applicable to accounts from the Account model

HTTP Request

POST https://login.eagleeyenetworks.com/g/aaa/switch_account

Parameter Data Type Description Required For
account_id string Id of the account to login to. Optional. Defaults to the account id that the user belongs to POST

Error Status Codes

HTTP Status Code Description
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
404 Account with the 'account_id’ provided cannot be found
200 Account context switch successful

Single Sign On

Request

curl --request POST https://login.eagleeyenetworks.com/g/sso

SSO allows a reseller to maintain account management and act as an identity provider to have their system proxy the authorization requests to Eagle Eye Network servers after users have logged into the identity providers system

This is done through the standard SAML (Security Assertion Markup Language) and as such the identity provider will setup their account with a brand_saml_publickey_ret and brand_saml_namedid_path.

Once the identity provider’s account has been registered for SSO, then the identity provider can validate their users and then make a single sign on request with the users email address and the return link. This 64 bit encrypted message will be extracted from the header to be decoded and verified using the saml public key. Then using the saml named id path, the user’s email will be extracted and an auth_key will be provided for that user.

HTTP Request

POST https://login.eagleeyenetworks.com/g/sso

Error Status Codes

HTTP Status Code Description
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
404 Account with the 'account_id’ provided cannot be found
200 Account context switch successful

Logout

Request

curl --cookie "auth_key=[AUTH_KEY]" --request POST https://login.eagleeyenetworks.com/g/aaa/logout

Log out user and invalidate HTTP session cookie

HTTP Request

POST https://login.eagleeyenetworks.com/g/aaa/logout

Error Status Codes

HTTP Status Code Description
400 Unexpected or non-identifiable arguments are supplied
204 User has been logged out

Account

Overview

The account service allows managing accounts by superusers and account superusers

Account Model

Account Model

{
    "is_master_video_disabled_allowed": 1,
    "is_inactive": 0,
    "is_suspended": 0,
    "brand_name": null,
    "alert_mode": [
        "default",
        "Weekend"
    ],
    "is_master_video_disabled": 0,
    "contact_state": null,
    "first_responders": [
        [
            "mark@responders.com",
            "Mark",
            "O'Malley",
            "Responders",
            "No Account"
        ],
        [
            "jeff@noaccount.com",
            "Jeff",
            "O'unverfied",
            "Unverfied Organization",
            "Fake Sponder"
        ],
        ...
    ],
    "contact_first_name": "Willem",
    "is_disable_all_settings": 0,
    "timezone": "US/Pacific",
    "id": "11111111",
    "contact_country": "US",
    "is_system_notifications_disabled": 0,
    "camera_shares": [
        [
            "10101010",
            "share@email.com",
            "hasno@account.com,No Account"
            ...
        ],
        ...
    ],
    "owner_account_id": "1010101b",
    "product_edition": null,
    "cc_info": [
        {
            "city": "",
            "name": "",
            "default": "",
            "street1": "",
            "street2": "",
            "number": "",
            "state": "",
            "tag": "",
            "postal_code": "",
            "expire": "",
            "country": "US",
            "type": ""
        }
    ],
    "brand_saml_publickey_cert": null,
    "brand_support_email": null,
    "is_billing_disabled": 0,
    "is_advanced_disabled": 0,
    "inactive_session_timeout": 720,
    "brand_logo_large": null,
    "brand_corp_url": null,
    "responder_active": true,
    "contact_street": [],
    "is_system_notification_images_enabled": 1,
    "is_custom_brand_allowed": 0,
    "holiday": [
        "20130101",
        "20130527",
        "20130704",
        "20130902",
        "20131128",
        "20131225"
    ],
    "is_rtsp_cameras_enabled": 0,
    "brand_saml_nameid_path": null,
    "is_contract_recording": 0,
    "utc_offset": -28800,
    "session_duration": 480,
    "is_custom_brand": 0,
    "contact_postal_code": null,
    "brand_logo_small": null,
    "is_active": 1,
    "work_days": "1111111",
    "is_add_delete_disabled": 0,
    "is_master": 0,
    "contact_email": "support@eagleeyenetworks.com",
    "responder_cameras": [
        "1010fake",
        "not1c4mr"
    ],
    "brand_support_phone": null,
    "map_lines": null,
    "contact_mobile_phone": null,
    "work_hours": [
        "0800",
        "1730"
    ],
    "login_attempt_limit": null,
    "default_cluster": "c9000",
    "customer_id": "1234",
    "name": "Account Name",
    "contact_city": null,
    "default_camera_passwords": "pwordpword",
    "contact_phone": null,
    "access_restriction": [
        "enable_mobile"
    ],
    "active_alert_mode": "default",
    "allowable_ip_address_range": [],
    "contact_last_name": "Dafoe",
    "contact_utc_offset": null,
    "camera_quantity": null,
    "brand_subdomain": "c9000"
}

Account Attributes

Parameter Data Type Description Editable Required
id string Unique identifier of the account false GET, POST, DELETE
name string Name of the account true PUT
owner_account_id string Id of the parent account. Defaults to the account of the creating user false
contact_first_name string First name of primary contact for account true PUT
contact_last_name string Last name of primary contact for account true PUT
contact_email string Email of primary contact for account true
contact_street array[string] Array of strings containing street addresses of the primary contact for account [‘address line 1’, 'address line 2’] true
contact_city string City of primary contact for account true
contact_state string State/province of primary contact for account true
contact_postal_code string Zip/postal code of primary contact for account true
contact_country string Country code of primary contact for account true
contact_phone string Phone number of primary contact for account true
contact_mobile_phone string Mobile phone number of primary contact for account true
timezone string Timezone of the account. Defaults to 'US/Pacific’. Possible values: 'US/Alaska’ or 'US/Arizona’ or 'US/Central’ or 'US/Eastern’ or 'US/Hawaii’ or 'America/Anchorage’ or 'UTC’ true
status array[string] Account status. This can only be edited by superusers and account superusers of the parent/owner account. Values: 'active’, 'inactive’, 'pending_validation’, 'suspended’. 'active’ mean account is in a normal working state. 'Inactive’ means logins are not allowed. 'Suspended’ means the account is effectively no longer operational ('pending_validation’ is the default state after first creation, before the user has validated the account) true
utc_offset int Signed integer offset in seconds of the timezone from UTC. Automatically generated based on the timezone field false
access_restriction array[string] Array of strings containing access restrictions. Possible values: 'enable_mobile’ = If present this account has access to mobile clients. 'enable_ip_restrictions’ = if present, and if 'allowable_ip_address_range’ has been specified, limits logins to the address ranges specified false
allowable_ip_address_range array[string] Each entry in the array specifies one address range. Entries use the ‘/’ format. For example, to limit access to 192.168.123.0-192.168.123.255, the entry would be 192.168.123.0/24. If no entries are present, 0.0.0.0/0 is implied false
session_duration int Session duration in minutes. Session duration of 0 means 'stay logged in forever’ true
holiday array[string] Array of strings containing dates during which holidays are observed. Format for dates is YYYYMMDD true
work_days string String of length 7. Each position in the string corresponds to a day of the week. Monday is position 0, Tuesday is position 1, etc. Each character in the string can have a value of 1 or 0. 1 means that this day is a work day true
work_hours array[string] Two entries. Each entry containing a time expressed in local time. The first entry in the array is the work day start time. The second entry in the array is the stop time. Times are represented using a 24 hour clock and are formatted as HHMM. For example, 8AM would be 0800 and 5PM would be 1700 true
alert_mode array[string] Array of strings containing possible alert modes as defined for this account. Accepts an array of any number of strings of varying length. This controls what values are able to be chosen for the 'active_alert_mode field’ true
active_alert_mode string A string chosen from values in the account 'alert_mode’ array. Must be blank or one of the values defined in the alert_mode array. This is used to determine when to send motion alert notifications (defined by camera settings in the device model). If a motion alert is defined with an alert mode from one of the strings in the account 'alert_mode’ array, then the notifications triggered from that motion alert will only be sent when the account 'active_alert_mode’ is also set to that same alert mode string defined for that motion alert true
default_camera_passwords string Comma-delimited string of default camera passwords true
camera_shares array[array[string]] Array of arrays, with each sub-array representing a camera to be shared to 1 or more recipients. First element of sub-array is action, with ’m’ for add/update. Second element of sub-array is camera id. Third element of sub-array is a string containing 1 or multiple recipients. Each recipient is a string value of 'email,account’, but only applies to the ’m’ action. Example: [[’m’, '12345678’, 'joe@em.com,His account’, joe2@dd.com,That account’]] true
is_revoke_admins int Indicates whether to revoke all admin permissions for the users in the account (1) or not (0). This field doesn’t save anything on the account itself. It will revoke admin privileges of any admins in the account true
is_master int Indicates whether the account is a master account (1) or not (0) false
is_active int Indicates whether the account is active (1) or not (0) false
is_inactive int Indicates whether the account is inactive (1) or not (0) true
is_suspended int Indicates whether the account is suspended (1) or not (0) true
product_edition string Product edition the account is using false
camera_quantity int Total number of cameras the account is allowed to use false
is_custom_brand_allowed int Indicates whether the account is allowed to have branding (1) or not (0) true
is_custom_brand int Indicates whether the account has branding enabled (1) or not (0) true
brand_logo_small string Base64 encoded image for the branded small logo (PNG, 160x52, transparent background) true
brand_logo_large string Base64 encoded image for the branded large logo (PNG, 460x184, white background) true
brand_subdomain string Sub domain for the branded url true
brand_corp_url string Corporate website url true
brand_name string Branded company name true
brand_saml_publickey_cert string Public certificate which Eagle Eye Networks will use to decrypt the SAML for SSO true
brand_saml_nameid_path string The path within the SAML xml to find the users email address true
is_without_initial_user string Indicates whether to create the new account without an initial user (1) or not (0). Defaults to 0, meaning an initial user with 'is_account_superuser=1’ will be created using the arguments 'contact_first_name/contact_last_name/contact_email’ specified upon account creation true
customer_id string Arbitrary id assigned to a sub-account by a master account true
is_master_video_disabled_allowed int Indicates whether a sub-account can block video access to reseller (1) or not (0) true
is_master_video_disabled int Indicates whether video access is blocked to reseller (1) or not (0) true
is_contract_recording int Indicates whether the account is of type contract_recording. Controls whether contract recording features are enabled for the users in this account on the front-end GUI (1) or not (0) true
is_advanced_disabled int Indicates whether the reseller has disabled advanced functionality (1) or not (0) If this is set for a sub-account, the users in the sub-account cannot change any settings related to bandwidth, billing (retention and resolution) and certain account settings. Master users switched in still can modify these things if their permissions allow it true
is_billing_disabled int Indicates whether the reseller has disabled editing settings in a sub-account that affect billing (1) or not (0). This controls whether users can change camera resolution/retention, add/delete cameras, etc true
is_add_delete_disabled int Indicates whether the reseller has disabled adding or deleting devices (1) or not (0) true
is_disable_all_settings int Indicates whether the reseller has disabled all device and most account settings (1) or not (0). Does not affect editing users, layouts, or sharing true
first_responders array[array[string]] Array of strings [['responder email’, 'responder first name’, 'responder last name’, 'responder organization’, 'responder account’]]. Accounts can identify a list of email accounts that will serve as emergency responders. Emergency responders get access to the identified cameras when an emergency is triggered by setting 'responder_active’ true
responder_active ??? Indicates whether the list of responder cameras can be seen by the list defined under 'first_responders’. Until this flag is set, responders cannot see the video true
responder_cameras array[string] Array of camera esns that are shared to first responders true
inactive_session_timeout int Maximum time period in seconds without activity before web session expires true
login_attempt_limit int Maximum incorrect login attempts before the user account access becomes locked true
is_rtsp_cameras_enabled int Indicates whether the account can have cameras attached over RTSP (instead of ONVIF) (1) or not (0) true
brand_support_phone string Branded support phone number true
default_cluster string Indicates the data center cluster the account is assigned to true
is_system_notification_images_enabled int Indicates whether email notifications about online/offlice status should contain images from those cameras (1) or not (0) true
map_lines string This is used by the front end to overlay lines over a map of the cameras for the account true
contact_utc_offset int Deprecated. This field is no longer being used true

Get Account

Request

curl -G https://login.eagleeyenetworks.com/g/account -d "id=[ID]&A=[AUTH_KEY]"

Return an Account object by id

HTTP Request

GET https://login.eagleeyenetworks.com/g/account

Parameter Data Type Description Is Required
id string Account id true

Error Status Codes

HTTP Status Code Description
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges
404 Account not found with the supplied ID
200 Request succeeded

Create Account

Request

curl --cookie "auth_key=[AUTH_KEY]" -X PUT -v -H "Authentication: [API_KEY]:" -H "content-type: application/json" https://login.eagleeyenetworks.com/g/account -d '{"name": "[NAME]", "contact_first_name": "[CONTACT_FIRST_NAME]", "contact_last_name": "[CONTACT_LAST_NAME]", "contact_email": "[CONTACT_EMAIL]"}'

Json Response

{
    "id": "1234abcd"
}

Create a new Account

HTTP Request

PUT https://login.eagleeyenetworks.com/g/account

Parameter Data Type Description Is Required
name string Name of the account true
owner_account_id string Id of the parent account. Defaults to the account of the creating user
contact_first_name string First name of primary contact for account true
contact_last_name string Last name of primary contact for account true
contact_email string Email of primary contact for account true
contact_street array[string] Array of strings containing street addresses of the primary contact for account ['address line 1’, 'address line 2’]
contact_city string City of primary contact for account
contact_state string State/province of primary contact for account
contact_postal_code string Zip/postal code of primary contact for account
contact_country string Country code of primary contact for account
timezone string Timezone of the account. Defaults to 'US/Pacific’. Possible values: 'US/Alaska’ or 'US/Arizona’ or 'US/Central’ or 'US/Eastern’ or 'US/Hawaii’ or 'America/Anchorage’ or 'UTC’
status array[string] Account status. This can only be edited by superusers and account superusers of the parent/owner account. 'realm_root’ can only be set by superusers
access_restriction array[string] Array of strings containing access restrictions. Possible values: 'enable_mobile’ = If present this account has access to mobile clients. 'enable_ip_restrictions’ = if present, and if 'allowable_ip_address_range’ has been specified, limits logins to the address ranges specified
allowable_ip_address_range array[string] Each entry in the array specifies one address range. Entries use the ‘/’ format. For example, to limit access to 192.168.123.0-192.168.123.255, the entry would be 192.168.123.0/24. If no entries are present, 0.0.0.0/0 is implied
session_duration int Session duration in minutes. Session duration of 0 means 'stay logged in forever’
holiday array[string] Array of strings containing dates during which holidays are observed. Format for dates is YYYYMMDD
work_days array[string] String of length 7. Each position in the string corresponds to a day of the week. Monday is position 0, Tuesday is position 1, etc. Each character in the string can have a value of 1 or 0. 1 means that this day is a work day
work_hours array[string] Two entries. Each entry containing a time expressed in local time. The first entry in the array is the work day start time. The second entry in the array is the stop time. Times are represented using a 24 hour clock and are formatted as HHMM. For example, 8AM would be 0800 and 5PM would be 1700
alert_mode array[string] Array of strings containing possible alert modes as defined for this account. Accepts an array of any number of strings of varying length. This controls what values are able to be chosen for the 'active_alert_mode field’
active_alert_mode string A string chosen from values in the account 'alert_mode’ array. Must be blank or one of the values defined in the alert_mode array. This is used to determine when to send motion alert notifications (defined by camera settings in the device model). If a motion alert is defined with an alert mode from one of the strings in the account 'alert_mode’ array, then the notifications triggered from that motion alert will only be sent when the account 'active_alert_mode’ is also set to that same alert mode string defined for that motion alert
default_camera_passwords string Comma-delimited string of default camera passwords
is_without_initial_user int Indicates whether to create the new account without an initial user (1) or not (0). Defaults to 0, meaning an initial user with 'is_account_superuser=1’ will be created using the arguments 'contact_first_name/contact_last_name/contact_email’ specified upon account creation
is_initial_user_not_admin int Indicates whether the initial user is an admin (0) or not (1)

Error Status Codes

HTTP Status Code Description
409 Another account with the supplied contact email address already exists

Update Account

Request

curl --cookie "auth_key=[AUTH_KEY]" -X POST -v -H "Authentication: [API_KEY]:" -H "content-type: application/json" https://login.eagleeyenetworks.com/g/account -d '{"id": "[ACCOUNT_ID]", "contact_first_name": "[CONTACT_FIRST_NAME]"}'

Json Response

{
    "id": "1234abcd"
}

Update an Account

HTTP Request

POST https://login.eagleeyenetworks.com/g/account

Parameter Data Type Description Is Required
id string Unique identifier of the account true
name string Name of the account
contact_first_name string First name of primary contact for account
contact_last_name string Last name of primary contact for account
contact_email string Email of primary contact for account
contact_street array[string] Array of strings containing street addresses of the primary contact for account ['address line 1’, 'address line 2’]
contact_city string City of primary contact for account
contact_state string State/province of primary contact for account
contact_postal_code string Zip/postal code of primary contact for account
contact_country string Country code of primary contact for account
contact_phone string Phone number of primary contact for account
contact_mobile_phone string Mobile phone number of primary contact for account
timezone string Timezone of the account. Defaults to 'US/Pacific’. Possible values: 'US/Alaska’ or 'US/Arizona’ or 'US/Central’ or 'US/Eastern’ or 'US/Hawaii’ or 'America/Anchorage’ or 'UTC’
status array[string] Account status. This can only be edited by superusers and account superusers of the parent/owner account. Values: 'active’, 'inactive’, 'pending_validation’, 'suspended’. 'active’ mean account is in a normal working state. 'Inactive’ means logins are not allowed. 'Suspended’ means the account is effectively no longer operational ('pending_validation’ is the default state after first creation, before the user has validated the account)
access_restriction array[string] Array of strings containing access restrictions. Possible values: 'enable_mobile’ = If present this account has access to mobile clients. 'enable_ip_restrictions’ = if present, and if 'allowable_ip_address_range’ has been specified, limits logins to the address ranges specified
allowable_ip_address_range array[string] Each entry in the array specifies one address range. Entries use the ‘/’ format. For example, to limit access to 192.168.123.0-192.168.123.255, the entry would be 192.168.123.0/24. If no entries are present, 0.0.0.0/0 is implied
session_duration int Session duration in minutes. Session duration of 0 means 'stay logged in forever’
holiday array[string] Array of strings containing dates during which holidays are observed. Format for dates is YYYYMMDD
work_days array[string] String of length 7. Each position in the string corresponds to a day of the week. Monday is position 0, Tuesday is position 1, etc. Each character in the string can have a value of 1 or 0. 1 means that this day is a work day
work_hours array[string] Two entries. Each entry containing a time expressed in local time. The first entry in the array is the work day start time. The second entry in the array is the stop time. Times are represented using a 24 hour clock and are formatted as HHMM. For example, 8AM would be 0800 and 5PM would be 1700
alert_mode array[string] Array of strings containing possible alert modes as defined for this account. Accepts an array of any number of strings of varying length. This controls what values are able to be chosen for the 'active_alert_mode field’
active_alert_mode string A string chosen from values in the account 'alert_mode’ array. Must be blank or one of the values defined in the alert_mode array. This is used to determine when to send motion alert notifications (defined by camera settings in the device model). If a motion alert is defined with an alert mode from one of the strings in the account 'alert_mode’ array, then the notifications triggered from that motion alert will only be sent when the account 'active_alert_mode’ is also set to that same alert mode string defined for that motion alert
default_camera_passwords string Comma-delimited string of default camera passwords
camera_shares array[array[string]] Array of arrays, with each sub-array representing a camera to be shared to 1 or more recipients. First element of sub-array is action, with ’m’ for add/update. Second element of sub-array is camera id. Third element of sub-array is a string containing 1 or multiple recipients. Each recipient is a string value of 'email,account’, but only applies to the ’m’ action. Example: [[’m’, '12345678’, 'joe@em.com,His account’, joe2@dd.com,That account’]]
is_revoke_admins int Indicates whether to revoke all admin permissions for the users in the account (1) or not (0). This field doesn’t save anything on the account itself. It will revoke admin privileges of any admins in the account
is_custom_brand int Indicates whether the account has branding enabled (1) or not (0)
brand_logo_small string Base64 encoded image for the branded small logo (PNG, 160x52, transparent background)
brand_logo_large string Base64 encoded image for the branded large logo (PNG, 460x184, white background)
brand_subdomain string Sub domain for the branded url
brand_corp_url string Corporate website url
brand_name string Branded company name
brand_saml_publickey_cert string Public certificate which Eagle Eye Networks will use to decrypt the SAML for SSO
brand_saml_nameid_path string The path within the SAML xml to find the users email address
is_master_video_disabled_allowed int Indicates whether a sub-account can block video access to reseller (1) or not (0)
is_master_video_disabled int Indicates whether video access is blocked to reseller (1) or not (0)
is_contract_recording int Indicates whether the account is of type contract_recording. Controls whether contract recording features are enabled for the users in this account on the front-end GUI (1) or not (0)
is_advanced_disabled int Indicates whether the reseller has disabled advanced functionality (1) or not (0). If this is set for a sub-account, the users in the sub-account cannot change any settings related to bandwidth, billing (retention and resolution) and certain account settings. Master users switched in still can modify these things if their permissions allow it
is_billing_disabled int Indicates whether the reseller has disabled editing settings in a sub-account that affect billing (1) or not (0). This controls whether users can change camera resolution/retention, add/delete cameras, etc
is_add_delete_disabled int Indicates whether the reseller has disabled adding or deleting devices (1) or not (0)
is_disable_all_settings int Indicates whether the reseller has disabled all device and most account settings (1) or not (0). Does not affect editing users, layouts, or sharing
first_responders array[array[string]] Array of strings [['responder email’, 'responder first name’, 'responder last name’, 'responder organization’, 'responder account’]]. Accounts can identify a list of email accounts that will serve as emergency responders. Emergency responders get access to the identified cameras when an emergency is triggered by setting 'responder_active’
responder_active ??? Indicates whether the list of responder cameras can be seen by the list defined under 'first_responders’. Until this flag is set, responders cannot see the video
responder_cameras array[string] Array of camera esns that are shared to first responders
inactive_session_timeout int Maximum time period in seconds without activity before web session expires
login_attempt_limit int Maximum incorrect login attempts before the user account access becomes locked
is_rtsp_cameras_enabled int Indicates whether the account can have cameras attached over RTSP (instead of ONVIF) (1) or not (0)
brand_support_phone string Branded support phone number
default_cluster string Indicates the data center cluster the account is assigned to
customer_id string Arbitrary id assigned to a sub-account by a master account
is_system_notification_images_enabled int Indicates whether email notifications about online/offlice status should contain images from those cameras (1) or not (0)
map_lines string This is used by the front end to overlay lines over a map of the cameras for the account
contact_utc_offset int Deprecated. This field is no longer being used

Error Status Codes

HTTP Status Code Description
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges
404 Account not found with the supplied ID
200 Request succeeded

Delete Account

Request

curl --cookie "auth_key=[AUTH_KEY]" -X DELETE -v -H "Authentication: [API_KEY]:" -H "content-type: application/json" https://login.eagleeyenetworks.com/g/account -d "id=[ACCOUNT_ID]" -G

Delete an Account

HTTP Request

DELETE https://login.eagleeyenetworks.com/g/account

Parameter Data Type Description
id string Account id

Error Status Codes

HTTP Status Code Description
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges
404 Account not found with the supplied ID
200 Delete succeeded

Get List of Accounts

Request

curl --cookie "auth_key=[AUTH_KEY]" --request GET https://login.eagleeyenetworks.com/g/account/list

Json Response

[
    [
        "00004206",
        "Greater God",
        0,
        0,
        1,
        0,
        0,
        1,
        null,
        0,
        0,
        0,
        0,
        0,
        0,
        "20160228234555.722",
        0,
        "Greater ID"
    ],
    [...],
    [...]
]

Return an array of arrays, with each sub-array representing an account available to the user. Please note that the account list model definition below has property keys, but that’s only for reference purposes since it’s actually just a standard array

HTTP Request

GET https://login.eagleeyenetworks.com/g/account/list

Account Array Attributes

Array Index Attribute Data Type Description
0 id string Unique identifier for the account
1 name string Name of the account
2 camera_online_count int Number of cameras currently online in the account
3 camera_count int Number of cameras currently in the account
4 user_count int Number of users currently in the account
5 is_suspended int Indicates whether the account is suspended (1) or not (0)
6 is_inactive int Indicates whether the account is inactive (1) or not (0)
7 is_active int Indicates whether the account is active (1) or not (0)
8 product_edition string Product edition the account is using
9 bridge_online_count int Number of online bridges owned by the account
10 bridge_active_count int Number of active bridges owned by the account
11 bridge_count int Number of bridges owned by the account
12 camera_off_count int Number of account cameras that are currently offline
13 camera_available_count int Number of available cameras in the account
14 is_account_active int Indicates the account is active (1) or not (0)
15 last_login string EEN timestamp of the last login by this account
16 average_retention_days int The average number of retention days for the account
17 customer_id string The customer id assigned to this account

Error Status Codes

HTTP Status Code Description
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges
200 Request succeeded

User

Overview

The user service allows managing users to a degree outlined by the permission level

User Model

User Model

{
    "id": "ca0e1cf2",
    "first_name": "Firstname",
    "last_name": "Lastname",
    "email": "john.doe@fakeemail.com",
    "owner_account_id": "00004206",
    "active_account_id": "00004206",
    "uid": " ",
    "is_superuser": 0,
    "is_account_superuser": 1,
    "is_staff": 0,
    "is_active": 1,
    "is_pending": 0,
    "is_master": 1,
    "is_user_admin": 1,
    "is_layout_admin": 1,
    "is_live_video": 1,
    "is_device_admin": 1,
    "is_export_video": 1,
    "is_recorded_video": 1,
    "is_edit_cameras": 1,
    "is_edit_all_users": 1,
    "is_edit_account": 1,
    "is_system_notifications_disabled": 0,
    "is_edit_ptz_stations": 1,
    "is_view_preview_video": 1,
    "is_edit_camera_on_off": 1,
    "is_edit_camera_less_billing": 1,
    "is_edit_all_and_add": 1,
    "is_edit_sharing": 1,
    "is_mobile_branded": 0,
    "is_edit_admin_users": 1,
    "is_view_contract": 1,
    "is_ptz_live": 1,
    "is_view_audit_trail": 1,
    "is_edit_users": 1,
    "is_edit_motion_areas": 1,
    "is_two_factor_authentication_enabled": 0,
    "user_authenticated_clients": null,
    "account_utc_offset": -21600,
    "account_work_days": "1111100",
    "account_work_hours": ["0800", "1730"],
    "language": "en-us",
    "inactive_session_timeout": 15,
    "street": ["address line 1", "address line 2"],
    "city": "New York",
    "state": "Alaska",
    "country": "US",
    "postal_code": "9980-999",
    "phone": "111111111",
    "mobile_phone": "000000000",
    "utc_offset": -21600,
    "timezone": "US/Pacific",
    "last_login": "20141006173752.672",
    "alternate_email": "alternate.email@fakeemail.com",
    "sms_phone": "222111222",
    "is_sms_include_picture": 0,
    "json": "{}",
    "camera_access": [
        [
            "1005f2ed",
            "r"
        ],
        [
            "100bd708",
            "r"
        ]
    ],
    "layouts": [
        "217f0fd4-450f-11e4-a983-ca8312ea370c"
    ],
    "is_notify_enable": 1,
    "notify_period": [
        "0-0000-2359",
        "1-0000-2359",
        "2-0000-2359",
        "3-0000-2359",
        "4-0000-2359",
        "5-0000-2359",
        "6-0000-2359"
    ],
    "notify_rule": [
        "one-email-0"
    ],
    "is_branded": 1,
    "active_brand_subdomain": "login",
    "account_map_lines": null,
    "access_period": [
        "0-0000-2359",
        "1-0000-2359",
        "2-0000-2359",
        "3-0000-2359",
        "4-0000-2359",
        "5-0000-2359",
        "6-0000-2359"
    ],
    "is_terms_noncompliant": 1
}

User Attributes

Parameter Data Type Description
id string Unique identifier of the user
first_name string First name of the user
last_name string Last name of the user
email string Email address of the user (must contain only ASCII characters)
owner_account_id string Unique identifier of the account that the user belongs to
active_account_id string Unique identifier of the user’s active account. When switching to a sub-account the ‘active_account_id’ of that user in their session becomes the unique identifier of the sub-account that was switched into
uid string Identifier of the user. This field is for internal use only
is_superuser int Indicates whether the user is a superuser (1) or not (0). Only superusers can set this. This field is for internal use only
is_account_superuser int Indicates whether the user is an account superuser (1) or not (0)
is_staff int Indicates whether the user is a staff member (1) or not (0). This field is for internal use only
is_active int Indicates whether the user is active (1) or not (0)
is_pending int Indicates whether the user is pending (1) or not (0)
is_master int Indicates whether the user is in a master account (1) or not (0)
is_user_admin int Deprecated. This is for backwards compatibility
is_layout_admin int Indicates whether the user is a layout administrator (1) or not (0)
is_live_video int Indicates whether the user is authorized to access live video (1) or not (0)
is_device_admin int Deprecated. This is for backwards compatibility
is_export_video int Indicates whether the user is authorized to export video (1) or not (0)
is_recorded_video int Indicates whether the user is authorized to view recorded video (1) or not (0)
is_edit_cameras int Indicates whether the user is authorized to edit cameras (1) or not (0)
is_edit_all_users int Indicates whether the user is authorized to manage users who are not administrators in the master account (1) or not (0)
is_edit_account int Indicates whether the user is authorized to edit account settings (1) or not (0)
is_system_notifications_disabled int It reflects whether the account the user belongs to has system notifications disabled (1) or not (0). If true, then the user will not be able to receive any system alert notifications for the cameras in their account
is_edit_ptz_stations int Indicates whether the user is authorized to edit PTZ stations (1) or not (0)
is_view_preview_video int Indicates whether the user is authorized to view preview images from cameras (1) or not (0)
is_edit_camera_on_off int Indicates whether the user is authorized to turn cameras on and off (1) or not (0)
is_edit_camera_less_billing int Indicates whether the user is authorized to edit all camera settings except retention and full video resolution (1) or not (0)
is_edit_all_and_add int Indicates whether the user is authorized to add/edit/delete bridges and cameras (1) or not (0)
is_edit_sharing int Indicates whether the user is authorized to view/edit 'Sharing’ and 'Responders’ tabs under account settings (1) or not (0)
is_mobile_branded int Used by mobile devices
is_edit_admin_users int Indicates whether the user is authorized to manage all users in sub-account (1) or not (0)
is_view_contract int Indicates whether the user is authorized to view contracts and replay them (1) or not (0)
is_ptz_live int Indicates whether the user is authorized to control pan, tilt, zoom, and recall stations while viewing preview or live video of PTZ cameras (1) or not (0)
is_view_audit_trail int Indicates whether the user is authorized to view the audit trail feature (1) or not (0)
is_edit_users int Indicates whether the user is authorized to manage users who are not administrators in a sub-account (1) or not (0)
is_edit_motion_areas int Indicates whether the user is authorized to view and edit the 'Motion’ tab under camera settings (1) or not (0)
is_two_factor_authentication_enabled int ???
user_authenticated_clients ??? ???
account_utc_offset int Signed integer offset in seconds of the timezone from UTC. This is the 'utc_offset’ value from the user’s associated account model
account_work_days string The 'work_days’ value from the user’s associated account model. Indicates which day is a work day
account_work_hours array[string] The 'work_hours’ value from the user’s associated account model. Indicates work hours for the account
language string Language code. The API currently only supports English (en-us) and Japanese (ja) as display languages for the GUI. It accepts any valid language code as input, but it will show English text for the unsupported languages
inactive_session_timeout int Maximum time period in seconds without activity before web session expires. Defined in the settings of the account which the user belongs to
street array[string] Array of strings containing street addresses ['address line 1’, 'address line 2’]
city string City
state string State/province
country string Two letter country code
postal_code string Zip/postal code
phone string Phone number
mobile_phone string Mobile phone number
utc_offset int Signed integer offset in seconds of the timezone from UTC. Automatically generated based on the timezone field
timezone string Timezone of the user. Defaults to 'US/Pacific’. Possible values: 'US/Alaska’ or 'US/Arizona’ or 'US/Central’ or 'US/Eastern’ or 'US/Hawaii’ or 'America/Anchorage’ or 'UTC’
last_login string EEN timestamp of the last login by the user. Format: YYYYMMDDHHMMSS.NNN
alternate_email string Alternate email address
sms_phone string Phone number to be used for SMS notifications
is_sms_include_picture int Indicates whether the alert notifications should include a picture sent via MMS to the sms_phone number (1) or not (0)
json string Misc settings of the user as a JSON string. UserJson
camera_access array[array[string]] Array of arrays, defined on a per device basis. Each sub-array contains two elements. The first field is the device unique identifier and the second field is a string of 1 or more characters indicating permissions of the user

Example: [‘cafedead’,’RWS’] = user can view, change and delete this device. [‘cafe0001’,’RW’] = user can view this layout and change this device

Permissions include: 'R’ - user has access to view images and video for this camera. 'A’ - user is an administrator for this camera. ’S’ - user can share this camera in a group share. Only superusers or account superusers can edit this field
layouts array[string] List of layout unique identifiers the user has access to
is_notify_enable int Indicates whether notifications are enabled for the user (1) or not (0)
notify_period array[string] Time periods during which the user will receive alert notifications. Each element of the array contains three fields separated by dashes. The first field is the day of the week where Monday is 0. The second element is the start time. The third element is the end time. If empty, user will not receive any alert notifications

All times are expressed in local time and use a 24 hour clock formatted as HHMM
notify_rule array[string] Alert notification rules. Each rule contains three fields separated by dashes in the form: Alert_Label-Notification_Method-Delay

Alert_Label: name defined by the user
Notification_Method: email, SMS, or GUI
Delay: amount of time in minutes between notifications
is_branded int Indicates whether the user is associated with an account that currently has branding enabled (1) or not (0)
active_brand_subdomain string If the user is associated with an account that has branding enabled, this will have that brand’s subdomain if one exists
account_map_lines json This is used by the front end to overlay lines over a map of the cameras for the account
access_period array[string] Contains the time periods during which the user has access to the account. Each element of the array contains three field separated by dashes. The first field is the day of the week where Monday is 0. The second element is the start time. The third element is the end time. If empty, user has no time restrictions for access to the account. All times are expressed in local time and use a 24 hour clock formatted as HHMM
is_terms_noncompliant int Indicates whether the terms of service have been accepted by the user (0) or not (1)

UserJson Attributes

Parameter Data Type Description
een json EEN Object. UserJsonEen

UserJsonEen Attributes

Parameter Data Type Description
show_AMPM boolean Indicates whether times should be shown with AM/PM (True) or not (False)
milliseconds_display boolean Indicates whether times should be shown with milliseconds (True) or not (False)
layout_rotation_seconds int If set, indicates how long to wait between layout changes during auto-rotation. If not set or set to 0, then no auto-rotation will occur
motion_boxes boolean Indicates whether motion boxes should be shown (True) or not (False)
notify_levels array[int] Array of integers. Indicates what types of alert notification emails will be sent

Notify level: 1='High’, 2='Low’, 3='System’

When creating motion alerts for a camera 'High’ or 'Low’ can be chosen. If a motion alert is set to 'High’ and if the user has chosen to receive 'High’ alert notifications, then they will receive them for that motion alert. 'System’ are camera status changes (online/offline/off/internet offline, etc.). When a camera changes status, any user who has chosen to receive 'System’ alert notifications will get notified of the camera status changes in their account
permissions json Deprecated. This is for backwards compatibility
employee_id string Identifier which a user with the necessary permissions can set for other users
layouts json JSON formatted data keyed by the account unique identifier, where each value is an array of globally unique identifiers of layouts in the account, ordered by how the user wants to see them in their graphical user interface

Permissions

There are several user types:

Account superuser
The account superuser has a full set of permissions. This user can manage all users in their account and sub-account. The fact that the user is administrator is indicated by flag: 'is_account_superuser’

Regular user
After being created the regular user has several default permissions : 'is_live_video’, 'is_recorded_video’, 'is_export_video’

List of permissions

Required Parameter Description
is_superuser Internal use only
is_staff Internal use only
is_account_superuser Highest permission level possible for a user. All permissions are enabled (including the view permission)
is_edit_account View and edit all account settings (including categories: Control, Days, Security, Camera, Alerts, Notifications, Privacy, Sharing, and Responders)
is_edit_camera_on_off Ability to turn cameras on and off. If this is the only camera permission granted all others are hidden
is_edit_cameras Allows editing all camera settings (does not allow adding or deleting cameras). View previews is enabled automatically with this permission
is_edit_motion_areas Enables the 'Motion’ tab under camera settings. View previews and view recorded video is enabled automatically with this permission
is_edit_ptz_stations Enables the 'PTZ’ tab under camera settings. Set PTZ mode and add/edit/delete stations. View previews is enabled automatically with this permission
is_edit_sharing Enables the 'Sharing’ and 'Responders’ tabs under Account Settings (This setting is not required if 'is_edit_account’ is enabled)
is_edit_users Enables the management of non-administrator users in a sub-account (add/delete/modify users). Gives the ability to grant access to cameras and layouts
is_export_video Enables to download preview and full resolution video. View previews is enabled automatically with this permission
is_edit_all_and_add Enables the management of bridges and cameras (add/edit/delete). Refers to devices only. View previews is enabled automatically with this permission
is_edit_camera_less_billing Allows editing all camera settings except retention and full video resolution (no ability to add/delete). View Previews is enabled automatically with this permission
is_layout_admin Enables the management of layouts (any user can create/edit/delete their own layouts. User layouts are always visible to admin users)
is_live_video Allows viewing full resolution video live from cameras. View previews is enabled automatically with this permission
is_ptz_live Enables the control over pan, tilt, zoom, and recall stations while viewing preview or live video of PTZ cameras. View previews is enabled automatically with this permission
is_recorded_video View history browser and archived video from cameras. View previews is enabled automatically with this permission
is_view_preview_video Enables the preview of images from cameras
is_edit_admin_users Enables the management of all users in a sub-account (add/delete/modify all users including administrators. Only available to Master Users)
is_edit_all_users Enables the management of master users who are not administrators (add/delete/modify master account users)

Ability to grant access to sub-accounts. No user permissions are granted in sub-accounts. Only available to master account users
is_device_admin Deprecated. This is for backwards compatibility
is_user_admin Deprecated. This is for backwards compatibility

User Permission Matrix

The table below shows which user management actions a user can execute depending on the account they belong to and which permission flags they have enabled

Who I am
In Master Account In Child Account
Account Superuser (ASU) Regular User (RU) Account Superuser (ASU) Regular User (RU)
What I can do In own account To ASU Get, Create, Update, Delete nothing Get, Create, Update, Delete nothing
To RU Get, Create, Update, Delete Get, Create, Update, Delete when is_edit_all_users == True Get, Create, Update, Delete Get, Create, Update, Delete when is_edit_users == True
Get list of users yes no yes no
In parent account To ASU Master Accounts have no parents nothing nothing
To RU nothing nothing
Get list of users no no
In child account To ASU Get, Create, Update, Delete Get, Create, Update, Delete when is_edit_admin_users == True Child accounts have no children
To RU Get, Create, Update, Delete Get, Create, Update, Delete when is_edit_users==True or is_edit_admin_users==True
Get list of users yes yes when is_edit_admin_users == True
In sibling account To ASU Master Accounts have no siblings nothing nothing
To RU nothing nothing
Get list of users no no

Get User

Request

curl -G https://login.eagleeyenetworks.com/g/user -d "A=[AUTH_KEY]"

or

curl --cookie "auth_key=[AUTH_KEY]" -G https://login.eagleeyenetworks.com/g/user -d id=[USER_ID]

Returns the user object by the unique identifier. If no unique identifier is passed in the request, then it will attempt to get the data of the user that is authenticated and making the call

HTTP Request

GET https://login.eagleeyenetworks.com/g/user

Parameter Data Type Description Is Required
id string Unique identifier of the user false

Error Status Codes

HTTP Status Code Description
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges
404 No user matching the unique identifier was found
200 Request succeeded

Create User

Request

curl --cookie "auth_key=[AUTH_KEY]" -X PUT -v -H "Authentication: [API_KEY]:" -H "content-type: application/json" https://login.eagleeyenetworks.com/g/user -d '{"first_name": "[FIRST_NAME]", "last_name": "[LAST_NAME]", "email": "[EMAIL]"}'

Json Response

{
    "id": "ca0ffa8c"
}

Creates a new user. After being created the user is in the pending state ('is_pending’:1, 'is_active’:0). The user creation email will be sent to the email address passed in the request. Then the user will be able to enter a password (In this step they may need to accept a terms of service). After this operation the user will be active ('is_pending’:0, 'is_active’:1)

HTTP Request

PUT https://login.eagleeyenetworks.com/g/user

Parameter Data Type Description
first_name string The first name of the user
last_name string The last name of the user
email string The email address of the user
sms_phone string Optional*
Phone number to be used for SMS notifications

* When TFA authentication scheme is used, and authorization code delivery via SMS at first user’s log in is required, the user’s SMS phone number must be specified at this time

Response Json Attributes

Parameter Data Type Description
id string Unique identifier of the user

Error Status Codes

HTTP Status Code Description
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges
409 The email address is currently already in use
200 Request succeeded

Update User

Request

curl --cookie "auth_key=[AUTH_KEY]" -X POST -v -H "Authentication: [API_KEY]:" -H "content-type: application/json" https://login.eagleeyenetworks.com/g/user -d '{"id": "[USER_ID]", "first_name": "[FIRST_NAME]"}'

Json Response

{
    "id": "ca0ffa8c"
}

Updates a user

HTTP Request

POST https://login.eagleeyenetworks.com/g/user

Parameter Data Type Description Is Required
id string Unique identifier of the user true
first_name string First name of the user
last_name string Last name of the user
email string Email address of the user (email must only contain ASCII characters)
phone string Phone number
mobile_phone string Mobile phone number
uid string Identifier of the user. Only superusers can set this. This field is for internal use only
owner_account_id string Unique identifier of the account that the user belongs to. Defaults to account of the user creating it (must be an account the user has access to)

For superusers: any account
For account superusers: their account or a child account
street array[string] Array of strings containing street addresses ['address line 1’, 'address line 2’]
city string City
state string State/province
country string Two letter country code
postal_code string Zip/postal code
json string JSON formatted data representing various user settings. UserJson
is_staff int Indicates whether the user is a staff member (1) or not (0). Only superusers can set this. This field is for internal use only
is_superuser int Indicates whether the user is a superuser (1) or not (0). Only superusers can set this. This field is for internal use only
is_account_superuser int Indicates whether the user is an account superuser (1) or not (0). Only superusers and account superusers can set this
is_layout_admin int Indicates whether the user is a layout administrator (1) or not (0)
is_device_admin int Deprecated. This is for backwards compatibility
is_user_admin int Deprecated. This is for backwards compatibility
is_live_video int Indicates whether the user is authorized to access live video (1) or not (0)
is_export_video int Indicates whether the user is authorized to export video (1) or not (0)
is_recorded_video int Indicates whether the user is authorized to view recorded video (1) or not (0)
is_edit_cameras int Indicates whether the user is authorized to edit cameras (1) or not (0)
is_edit_all_users int Indicates whether the user is authorized to manage users who are not administrators in master account (1) or not (0)
is_edit_account int Indicates whether the user is authorized to edit account settings (1) or not (0)
is_edit_ptz_stations int Indicates whether the user is authorized to edit PTZ stations (1) or not (0)
is_view_preview_video int Indicates whether the user is authorized to view preview images from cameras (1) or not (0)
is_edit_camera_on_off int Indicates whether the user is authorized to turn cameras on and off (1) or not (0)
is_edit_camera_less_billing int Indicates whether the user is authorized to edit all camera settings except retention and full video resolution (1) or not (0)
is_edit_all_and_add int Indicates whether the user is authorized to add/edit/delete bridges and cameras (1) or not (0)
is_edit_sharing int Indicates whether the user is authorized to view/edit 'Sharing’ and 'Responders’ tabs under account settings (1) or not (0)
is_ptz_live int Indicates whether the user is authorized to control pan, tilt, zoom, and recall stations while viewing preview or live video of PTZ cameras (1) or not (0)
is_edit_users int Indicates whether the user is authorized to manage users who are not administrators in a sub-account (1) or not (0)
is_edit_admin_users int Indicates whether the user is authorized to manage all users in sub-account (1) or not (0)
is_edit_motion_areas int Indicates whether the user is authorized to view and edit the 'Motion’ tab under camera settings (1) or not (0)
camera_access array Array of arrays, defined on a per device basis. Each sub-array contains two elements. The first field is the device unique identifier and the second field is a string of 1 or more characters indicating permissions of the user

Example: [‘cafedead’,’RWS’] = user can view, change and delete this device. [‘cafe0001’,’RW’] = user can view this layout and change this device

Permissions include: 'R’ - user has access to view images and video for this camera. 'A’ - user is an administrator for this camera. ’S’ - user can share this camera in a group share. Only superusers or account superusers can edit this field
sms_phone string Phone number to be used for SMS notifications
is_sms_include_picture int Indicates whether the alert notifications should include a picture sent via MMS to the sms_phone number (1) or not (0)
alternate_email string Alternate email address
timezone string Timezone of the user. Defaults to 'US/Pacific’. Possible values: 'US/Alaska’ or 'US/Arizona’ or 'US/Central’ or 'US/Eastern’ or 'US/Hawaii’ or 'America/Anchorage’ or 'UTC’
access_period array Contains the time periods during which the user has access to the account. Each element of the array contains three field separated by dashes. The first field is the day of the week where Monday is 0. The second element is the start time. The third element is the end time. If empty, user has no time restrictions for access to the account. All times are expressed in local time and use a 24 hour clock formatted as HHMM
notify_period array Time periods during which the user will receive alert notifications. Each element of the array contains three fields separated by dashes. The first field is the day of the week where Monday is 0. The second element is the start time. The third element is the end time. If empty, user will not receive any alert notifications

All times are expressed in local time and use a 24 hour clock formatted as HHMM
is_notify_enable int Indicates whether notifications are enabled for the user (1) or not (0)
notify_rule array Alert notification rules. Each rule contains three fields separated by dashes in the form: Alert_Label-Notification_Method-Delay

Alert_Label: name defined by the user
Notification_Method: email, SMS, or GUI
Delay: amount of time in minutes between notifications
language string Language code. The API currently only supports English (en-us) and Japanese (ja) as display languages for the GUI. It accepts any valid language code as input, but it will show English text for the unsupported languages
is_view_contract int Indicates whether the user is authorized to view contracts and replay them (1) or not (0)

Response Json Attributes

Parameter Data Type Description
id string Unique identifier of the user

Error Status Codes

HTTP Status Code Description
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges
404 No user matching the unique identifier was found
200 Request succeeded

Delete User

Request

curl --cookie "auth_key=[AUTH_KEY]" -X DELETE -v -H "Authentication: [API_KEY]:" -H "content-type: application/json" https://login.eagleeyenetworks.com/g/user -d "id=[USER_ID]" -G

Deletes a user

HTTP Request

DELETE https://login.eagleeyenetworks.com/g/user

Parameter Data Type Description
id string Unique identifier of the user

Error Status Codes

HTTP Status Code Description
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges
404 No user matching the unique identifier was found
200 Request succeeded

Get List of Users

Request

curl --cookie "auth_key=[AUTH_KEY]" --request GET https://login.eagleeyenetworks.com/g/user/list

Json Response

[
    [
        "ca0555c7",
        "Katherine",
        "Xiao",
        "katherine.xiao@fakeemail.com",
        [
            "export_video",
            "recorded_video",
            "live_video",
            "device_admin",
            "layout_admin",
            "account_superuser",
            "user_admin",
            "active"
        ],
        "20140929154619.000"
    ],
    [
        "ca00783b",
        "George",
        "Adams",
        "george.adams@fakeemail.com",
        [
            "export_video",
            "recorded_video",
            "live_video",
            "active"
        ],
        "20140716205645.000"
    ],
    [...],
    [...],
    [...]
]

Returns array of arrays, with each sub-array representing a user available to the current user. Please note that the model definition below has property keys, but that’s only for reference purposes since it’s actually just a standard array

HTTP Request

GET https://login.eagleeyenetworks.com/g/user/list

User Array Attributes

Array Index Attribute Data Type Description
0 id string Unique identifier of the user
1 first_name string First name of the user
2 last_name string Last name of the user
3 email string Email address of the user
4 permissions array[string] List of permissions of the user
5 last_login string EEN timestamp of the last login by the user. Format: YYYYMMDDHHMMSS.NNN

Error Status Codes

HTTP Status Code Description
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges
200 Request succeeded

Camera

Overview

The Device service allows access to create new logical devices (Cameras or Bridges) and establish a relationship between logical and physical devices. Get method is available to any user with camera ‘R’ (read) permission. Methods Post, Delete are available to account super users and users with Camera ‘W’ (write) permissions for the indicated camera. Put method is only available to account super users.

When adding a new camera, the name and settings parameters are required. The settings parameter should contain the id of the bridge and the guid of the camera.

Camera Settings Overview

The camera setting system is based on an inheritance model. User settings are “overlayed” on top of default settings for a device. By removing the user settings, the camera setting will automatically go back to the default value provided and maintained by Eagle Eye for the camera.

Under the covers this works as follows:

The implication of this is that if a user has not “pinned” a setting by changing/managing it, it will track any system or make/model/version release updates. That is, EEN can optimize operating parameters and they will automatically propagate unless the user has changed/pinned them. Further, the user should be “aware” of this, which works well with an open/closed control metaphor or a check box - an y setting control that is open/checked is “manually” set by the user, whereas closed controls will track EEN system wide recommendations. Finally, it is expected that the “user” settings will be managed to be only the value specifically modified by users, not all settings.

The set of all settings is potentially large, and far more than most users will ever want or need to manage. A separate table will be maintained which lists the “normal” settings - settings most users may want to interact with. This is standard across all devices, and contains a list of settings names that should be accessible to the user. This list should be “joined” with the list of all settings to result in a subset of controls to be displayed in basic mode. An advanced mode should make all settings available with primitive controls to set or delete a value.

An implication of this model the “user settings” object is a generic object that is only lightly interpreted by the device. Settings that match a known names (ie are within the camera base or mmv settings) will be utilized, but all values will be stored and returned as part of the “user settings” field. This can be used to support user interface elements on a per camera basis with values the bridge/camera do not interpret.

Read Camera Settings (GET device “camera_settings” property)

When getting the camera settings, a JSON string representing a JSON object is returned containing:

Update Camera Settings (POST device “camera_settings_add” argument)

To update/set settings (i.e. override default setting value with a “user” setting), a JSON string is sent representing a JSON object containing:

Delete Camera Settings (POST device “camera_settings_delete” argument)

To delete/unset settings (i.e. return to default setting value), a JSON string is sent representing a JSON object containing:

Camera Settings Currently Supported

Each camera make/model/version is different, thus not every setting is supported for some cameras, but here is list of core camera settings that are relevant to most applications:

Regions of Interest (ROIs)

ROIs will be defined by simple polygons - sequences of x,y coordinates that form a closed object, edge crosses are illegal and will have bizarre results. Each ROI will describe a portion of the screen. ROIs can overlap, and priority (higher wins) determines what sensitivity settings to use. For overlapping ROIs, all will get motion block detection and can trigger ROI motion spans.

ROIs can

ROIs within settings will be “rois”: { “roiname”: roi,… }. ROIs are enabled and disabled by “active_rois”: { “roiname”: true,…} to allow ROIs to easily turned on and off to support schedules and ROI based alerts. To remove an active ROI delete it with the same arguments.

Like the alert logic, “rois” and “active_rois” are accumulation settings - adding an object adds it to the holding object instead of replacing the entire object like most settings. Similarly, deleting an object removes it from the parent object, but leave the parent in place. Both also automatically trigger updates to the active esn data streams.

ROIs can produce events and force video recording on activity within them. These events are distinct from motion events (whole screen events). Each ROI event has a simple snapshot algorithm the grabs a snapshot immediately, as opposed to the optimized object tracking for motion events. Since ROIs are presumed to be smaller, this should result in good summary images.

ROI events are reported by the ROMS and ROME etags

ROMS

ROME

Camera Model

Camera Model

{
    "id": "1000f60d",
    "name": "Kitchen",
    "utcOffset": -18000,
    "timezone": "US/Central",
    "guid": "c6d11f36-9e63-11e1-a5b0-00408cdf9191",
    "permissions": "swr",
    "tags": [
        "austin",
        "kitchen"
    ],
    "bridges": {
        "100a9af6": "ATTD"
    },
    "settings": {
        "username": "onvif",
        "password": "securityCameraz",
        "bridge": "100a9af6",
        "roi_names": {},
        "alert_notifications": {},
        "alert_modes": {},
        "alert_levels": {},
        "notes": "",
        "longitude": -97.740714999999994,
        "latitude": 30.269064,
        "street_address": "717-799 Brazos Street, Austin, TX 78701, USA",
        "azimuth": 257.47226999999998,
        "range": 17.983694,
        "floor": 16,
        "share_email": "mcazares+videotest@eagleeyenetworks.com",
        "retention_days": 30,
        "cloud_retention_days": 30
    },
    "camera_info_status_code": 200,
    "camera_info": {
        "bridge": "bf5ce89d-8dbb-4eed-a2a8-60971e6d447e",
        "camera_state_version": 0,
        "intf": "Camera LAN",
        "camera_retention": 2592000000,
        "tagmap_status_state": 2,
        "camera_newest": "20141006190516.702",
        "camera_oldest": "20140906000000.000",
        "connect": "STRM",
        "uuid": "c6d11f36-9e63-11e1-a5b0-00408cdf9191",
        "service": "ATTD",
        "make": "AXIS",
        "ipaddr": "*169.254.12.141,10.143.236.65",
        "ts": "20141006182806.570",
        "version": "5.40.9.2",
        "admin_password": null,
        "esn": "1000f60d",
        "status": "1966143",
        "admin_user": null,
        "register_id": 0,
        "mac": "00:40:8C:DF:91:91",
        "proxy": "secondary",
        "bridgeid": "100a9af6",
        "now": "20141006210729.065",
        "class": "camera",
        "status_hex": "001e003f",
        "camera_now": "20141006210729.688",
        "camera_abs_newest": "20141006190516.702",
        "camera_abs_oldest": "20140906000000.000",
        "model": "AXIS M1054",
        "camtype": "ONVIF"
    },
    "camera_parameters_status_code": 200,
    "camera_parameters": {
        "active_settings": {
            "bandwidth_background": {
                "max": 10000000000.0,
                "min": -1000.0,
                "d": 0.0,
                "v": 0.0
            },
            "preview_jcmp_enable": {
                "max": 1,
                "min": 0,
                "d": 1,
                "v": 1
            },
            "bandwidth_recover": {
                "max": 10000000000.0,
                "min": 0.0,
                "d": 0.0,
                "v": 0.0
            },
            "video_transmit_mode": {
                "min": [
                    "always",
                    "event",
                    "background",
                    "on demand"
                ],
                "d": "background",
                "v": "background"
            },
            "preview_noise_limit_default": {
                "max": 16,
                "min": 2,
                "d": 16,
                "v": 16
            },
            "video_resolution": {
                "min": [
                    "cif",
                    "std",
                    "high"
                ],
                "d": "high",
                "v": "high"
            },
            "retention_days": {
                "max": 10000,
                "min": 1,
                "d": 14,
                "v": 30
            },
            "bridge_retention_days": {
                "max": 100000,
                "min": 0,
                "d": 0,
                "v": 0
            },
            "stream_stats": {
                "d": "none",
                "v": "none"
            },
            "motion_edge_expand_ratio": {
                "max": 0.98999999999999999,
                "min": 0.001,
                "d": 0.10000000000000001,
                "v": 0.10000000000000001
            },
            "preview_resolution": {
                "min": [
                    "cif",
                    "std",
                    "high"
                ],
                "d": "cif",
                "v": "std"
            },
            "display_features": {
                "max": 255,
                "min": 0,
                "d": 255,
                "v": 255
            },
            "motion_event_holdoff_ms": {
                "max": 1000,
                "min": 0,
                "d": 300,
                "v": 300
            },
            "retention_max_bytes": {
                "max": 1000000000000.0,
                "min": 0,
                "d": 0.0,
                "v": 0.0
            },
            "active_rois": {
                "d": {},
                "v": {}
            },
            "video_config": {
                "d": {
                    "preview_profile": "een_prvw",
                    "video_profile": "een_video",
                    "preview_quality_settings": {
                        "high": {
                            "h": 720,
                            "quality": {
                                "high": {
                                    "q": 80,
                                    "kbps": 1600,
                                    "fps": 4
                                },
                                "med": {
                                    "q": 60,
                                    "kbps": 1000,
                                    "fps": 4
                                },
                                "low": {
                                    "q": 40,
                                    "kbps": 800,
                                    "fps": 4
                                }
                            },
                            "w": 1280
                        },
                        "std": {
                            "h": "360",
                            "quality": {
                                "high": {
                                    "q": 80,
                                    "kbps": 500,
                                    "fps": 4
                                },
                                "med": {
                                    "q": 60,
                                    "kbps": 350,
                                    "fps": 4
                                },
                                "low": {
                                    "q": 40,
                                    "kbps": 250,
                                    "fps": 4
                                }
                            },
                            "w": 640
                        },
                        "cif": {
                            "h": "180",
                            "quality": {
                                "high": {
                                    "q": 80,
                                    "kbps": 200,
                                    "fps": 4
                                },
                                "med": {
                                    "q": 60,
                                    "kbps": 150,
                                    "fps": 4
                                },
                                "low": {
                                    "q": 40,
                                    "kbps": 100,
                                    "fps": 4
                                }
                            },
                            "w": 320
                        }
                    },
                    "video_quality_settings": {
                        "high": {
                            "h": 720,
                            "quality": {
                                "high": {
                                    "q": 80,
                                    "kbps": 2000,
                                    "fps": 30
                                },
                                "med": {
                                    "q": 60,
                                    "kbps": 1000,
                                    "fps": 15
                                },
                                "low": {
                                    "q": 40,
                                    "kbps": 500,
                                    "fps": 10
                                }
                            },
                            "w": 1280
                        },
                        "std": {
                            "h": "360",
                            "quality": {
                                "high": {
                                    "q": 80,
                                    "kbps": 600,
                                    "fps": 30
                                },
                                "med": {
                                    "q": 60,
                                    "kbps": 400,
                                    "fps": 15
                                },
                                "low": {
                                    "q": 40,
                                    "kbps": 200,
                                    "fps": 10
                                }
                            },
                            "w": 640
                        },
                        "cif": {
                            "h": "180",
                            "quality": {
                                "high": {
                                    "q": 80,
                                    "kbps": 300,
                                    "fps": 30
                                },
                                "med": {
                                    "q": 60,
                                    "kbps": 140,
                                    "fps": 15
                                },
                                "low": {
                                    "q": 40,
                                    "kbps": 70,
                                    "fps": 10
                                }
                            },
                            "w": 320
                        }
                    }
                },
                "v": {
                    "preview_profile": "een_prvw",
                    "video_profile": "een_video",
                    "preview_quality_settings": {
                        "high": {
                            "h": 720,
                            "quality": {
                                "high": {
                                    "q": 80,
                                    "kbps": 1600,
                                    "fps": 4
                                },
                                "med": {
                                    "q": 60,
                                    "kbps": 1000,
                                    "fps": 4
                                },
                                "low": {
                                    "q": 40,
                                    "kbps": 800,
                                    "fps": 4
                                }
                            },
                            "w": 1280
                        },
                        "std": {
                            "h": "360",
                            "quality": {
                                "high": {
                                    "q": 80,
                                    "kbps": 500,
                                    "fps": 4
                                },
                                "med": {
                                    "q": 60,
                                    "kbps": 350,
                                    "fps": 4
                                },
                                "low": {
                                    "q": 40,
                                    "kbps": 250,
                                    "fps": 4
                                }
                            },
                            "w": 640
                        },
                        "cif": {
                            "h": "180",
                            "quality": {
                                "high": {
                                    "q": 80,
                                    "kbps": 200,
                                    "fps": 4
                                },
                                "med": {
                                    "q": 60,
                                    "kbps": 150,
                                    "fps": 4
                                },
                                "low": {
                                    "q": 40,
                                    "kbps": 100,
                                    "fps": 4
                                }
                            },
                            "w": 320
                        }
                    },
                    "video_quality_settings": {
                        "high": {
                            "h": 720,
                            "quality": {
                                "high": {
                                    "q": 80,
                                    "kbps": 2000,
                                    "fps": 30
                                },
                                "med": {
                                    "q": 60,
                                    "kbps": 1000,
                                    "fps": 15
                                },
                                "low": {
                                    "q": 40,
                                    "kbps": 500,
                                    "fps": 10
                                }
                            },
                            "w": 1280
                        },
                        "std": {
                            "h": "360",
                            "quality": {
                                "high": {
                                    "q": 80,
                                    "kbps": 600,
                                    "fps": 30
                                },
                                "med": {
                                    "q": 60,
                                    "kbps": 400,
                                    "fps": 15
                                },
                                "low": {
                                    "q": 40,
                                    "kbps": 200,
                                    "fps": 10
                                }
                            },
                            "w": 640
                        },
                        "cif": {
                            "h": "180",
                            "quality": {
                                "high": {
                                    "q": 80,
                                    "kbps": 300,
                                    "fps": 30
                                },
                                "med": {
                                    "q": 60,
                                    "kbps": 140,
                                    "fps": 15
                                },
                                "low": {
                                    "q": 40,
                                    "kbps": 70,
                                    "fps": 10
                                }
                            },
                            "w": 320
                        }
                    }
                }
            },
            "video_capture_mode": {
                "min": [
                    "always",
                    "event"
                ],
                "d": "event",
                "v": "event"
            },
            "motion_noise_filter": {
                "max": 1.0,
                "min": 0.0,
                "d": 0.69999999999999996,
                "v": 0.69999999999999996
            },
            "motion_event_holdon_ms": {
                "max": 1000,
                "min": 0,
                "d": 300,
                "v": 300
            },
            "preview_realtime_bandwidth": {
                "max": 100000000.0,
                "min": 8000.0,
                "d": 50000.0,
                "v": 400000.0
            },
            "motion_snap_size_ratio": {
                "max": 0.98999999999999999,
                "min": 0.0001,
                "d": 0.001,
                "v": 0.001
            },
            "preview_history_depth_ms": {
                "max": 32000,
                "min": 1000,
                "d": 4000,
                "v": 4000
            },
            "encryption_type": {
                "max": 1,
                "min": 0,
                "d": 0,
                "v": 0
            },
            "event_postroll_ms": {
                "max": 5000,
                "min": 0,
                "d": 1000,
                "v": 1000
            },
            "alerts": {
                "d": {},
                "v": {}
            },
            "preview_interval_ms": {
                "max": 16000,
                "min": 250,
                "d": 1000,
                "v": 1000
            },
            "motion_snap_age_threshold_ms": {
                "max": 2000,
                "min": 100,
                "d": 200,
                "v": 200
            },
            "preview_key_frame_hold_ms": {
                "max": 3600000,
                "min": 30000,
                "d": 1800000,
                "v": 1800000
            },
            "display_width": {
                "max": 64000,
                "min": 80,
                "d": 320,
                "v": 320
            },
            "preview_min_gop_ms": {
                "max": 180000,
                "min": 1000,
                "d": 4000,
                "v": 4000
            },
            "preview_first_frame_delta_target": {
                "max": 0.98999999999999999,
                "min": 0.01,
                "d": 0.25,
                "v": 0.25
            },
            "motion_logmask": {
                "max": 7,
                "min": 0,
                "d": 0,
                "v": 0
            },
            "preview_log_mask": {
                "max": 15,
                "min": 0,
                "d": 0,
                "v": 0
            },
            "local_retention_days": {
                "max": -1,
                "min": -1,
                "d": -1,
                "v": -1
            },
            "preview_noise_limit_min": {
                "max": 16,
                "min": 2,
                "d": 3,
                "v": 3
            },
            "motion_hold_interval": {
                "max": 120.0,
                "min": 0.0,
                "d": 5.0,
                "v": 5.0
            },
            "stream_stats_present_only": {
                "max": 1,
                "min": 0,
                "d": 1,
                "v": 1
            },
            "active_alerts": {
                "d": {},
                "v": {}
            },
            "motion_weights": {
                "max": 64,
                "length": 8,
                "min": 1,
                "d": [
                    8,
                    4,
                    2,
                    1,
                    1,
                    1,
                    1,
                    1
                ],
                "v": [
                    "8",
                    "4",
                    "2",
                    "1",
                    "1",
                    "1",
                    "1",
                    "1"
                ]
            },
            "preview_min_limit_change_ms": {
                "max": 500000,
                "min": 2000,
                "d": 10000,
                "v": 10000
            },
            "preview_transmit_mode": {
                "min": [
                    "always",
                    "event",
                    "background",
                    "on demand"
                ],
                "d": "always",
                "v": "always"
            },
            "bandwidth_demand": {
                "max": 10000000000.0,
                "min": 0.0,
                "d": 0.0,
                "v": 0.0
            },
            "audio_enable": {
                "d": false,
                "v": true
            },
            "video_bandwidth_factor": {
                "max": 64,
                "min": 0,
                "d": 0,
                "v": 0
            },
            "shaping_mode": {
                "max": 127,
                "min": 0,
                "d": 31,
                "v": 31
            },
            "display_name": {
                "d": "none",
                "v": "none"
            },
            "display_height": {
                "max": 64000,
                "min": 80,
                "d": 180,
                "v": 180
            },
            "preview_compress_keyframes": {
                "max": 1,
                "min": 0,
                "d": 0,
                "v": 0
            },
            "motion_snap_push_min_delay_ms": {
                "max": 5000,
                "min": 1000,
                "d": 2000,
                "v": 2000
            },
            "motion_size_ratio": {
                "max": 0.98999999999999999,
                "min": 0.0001,
                "d": 0.001,
                "v": 0.001
            },
            "video_quality": {
                "min": [
                    "low",
                    "med",
                    "high"
                ],
                "d": "med",
                "v": "med"
            },
            "video_source_flip": {
                "d": false,
                "v": false
            },
            "motion_sensitivity": {
                "max": 1.0,
                "min": 0.0,
                "d": 0.80000000000000004,
                "v": 0.80000000000000004
            },
            "motion_size_metric_active": {
                "max": 1,
                "min": 0,
                "d": 0,
                "v": 0
            },
            "camera_on": {
                "max": 1,
                "min": 0,
                "d": 1,
                "v": 1
            },
            "motion_snap_excellent_hold_ms": {
                "max": 5000,
                "min": 100,
                "d": 1000,
                "v": 1000
            },
            "cloud_retention_days": {
                "max": 365,
                "min": 1,
                "d": 14,
                "v": 30
            },
            "video_source_bounds": {
                "max": [
                    1440,
                    900,
                    1440,
                    900
                ],
                "min": [
                    0,
                    0,
                    0,
                    0
                ],
                "d": [
                    0,
                    0,
                    1440,
                    900
                ],
                "v": [
                    0,
                    0,
                    1440,
                    900
                ]
            },
            "rois": {
                "d": {},
                "v": {}
            },
            "preview_max_gop_ms": {
                "max": 180000,
                "min": 5000,
                "d": 30000,
                "v": 30000
            },
            "retention_priority": {
                "max": 10000,
                "min": 1,
                "d": 100,
                "v": 100
            },
            "preview_noise_change_threshold": {
                "max": 64,
                "min": 1,
                "d": 2,
                "v": 2
            },
            "preview_quality": {
                "min": [
                    "low",
                    "med",
                    "high"
                ],
                "d": "med",
                "v": "med"
            },
            "motion_expand_ratio": {
                "max": 0.98999999999999999,
                "min": 0.001,
                "d": 0.10000000000000001,
                "v": 0.10000000000000001
            },
            "motion_boxes_metric_active": {
                "max": 1,
                "min": 0,
                "d": 0,
                "v": 0
            },
            "event_preroll_ms": {
                "max": 5000,
                "min": 0,
                "d": 1000,
                "v": 1000
            },
            "preview_queue_ms": {
                "max": 20000,
                "min": 1000,
                "d": 10000,
                "v": 10000
            }
        },
        "active_filters": [
            "user_user"
        ],
        "user_settings": {
            "versions": {},
            "settings": {
                "preview_realtime_bandwidth": 400000,
                "retention_days": 30,
                "cloud_retention_days": 30,
                "preview_resolution": "std",
                "audio_enable": true,
                "motion_weights": [
                    "8",
                    "4",
                    "2",
                    "1",
                    "1",
                    "1",
                    "1",
                    "1"
                ]
            },
            "schedules": {}
        }
    }
}

Device Attributes

Parameter Data Type Description
id string Unique identifier for the Device
name string Name of the device
utcOffset int Signed UTC offset in seconds of the timezone from UTC, where this device is installed.
timezone string Supported timezones: If this is a bridge, defaults to the Account timezone. If this is a camera, defaults to the camers’s Bridge timezone. Otherwise defaults to US/Pacific.

enum: US/Alaska, US/Arizona, US/Central, US/Pacific, US/Eastern, US/Mountain, US/Hawaii, UTC
guid string guid or other physical identifier of device
permissions string String of one or more characters. Each character defines a permission. Permissions include: ‘R’ - user has access to view images and video for this camera. 'A’ - user is an admin for this camera. ’S’ - user can share this camera in a group share. Note: All cameras in a group must have the ‘S’ permission or the group cannot be shared
tags array[string] Array of strings, which each string representing a “tag”
bridges DeviceBridges Bridges this device is seen by
settings DeviceSettings Misc settings
camera_parameters object JSON object of camera parameters/settings (see Overview for details). If camera parameters cannot be retrieved for whatever reason (such as when communication with camera has been lost), then this will be empty, and camera_parameters_status_code will be 404.
camera_parameters_status_code int 200 if camera_parameters were retrieved. 404 if camera_parameters were unable to be retrieved.
camera_info DeviceCameraInfo Camera related info, which only applies to devices that are cameras
camera_info_status_code int 200 if camera_info was retrieved. 404 if camera_info was unable to be retrieved.

DeviceSettings Attributes

Parameter Data Type Description
username string Username to login to camera. Only applies to Cameras.
password string Password to login to camera. Only applies to Cameras.
bridge string Device ID of bridge to attach camera to. Only applies to Cameras. Required for PUT for Cameras.
guid string GUID of physical device. Only applies to Cameras. Required for PUT for Cameras.
roi_names DeviceSettingsRoiNames ROI names keyed by ROI ID. Only applies to Cameras.
alert_notifications DeviceSettingsAlertNotifications Arrays of User IDs keyed by ROI ID. Only applies to Cameras.
alert_modes DeviceSettingsAlertModes Arrays of Alert modes keyed by ROI ID. Only applies to Cameras.
alert_levels DeviceSettingsAlertLevels Arrays of Alert levels keyed by ROI ID. Only applies to Cameras.
notes string Notes
latitude float Latitude of the cameras location.
longitude float Longitude of the cameras location.
street_address string Street Address of the cameras location.
azimuth float Direction that the center of the camera faces. Values from 0.0-360.0 North=0.0.
range int Effective distance the camera can 'see’ in feet.
floor int The floor of the building given that it is multiple stories.
share_email string Comma delimited list of emails to share this device with
local_retention_days json JSON object of total retention days e.g. {"max": 10000,"min": 1,"d": 14,"v": 14}
cloud_retention_days json JSON object of retention days in the cloud e.g. {"max": 10000,"min": 1,"d": 14,"v": 14}
bridge_retention_days json JSON object of retention days on the bridge e.g. {"max": 10000,"min": 1,"d": 14,"v": 14}

DeviceCameraInfo Attributes

Parameter Data Type Description
bridge string GUID of bridge the camera is attached to
camera_retention int Retention period in milliseconds
camera_newest string Timestamp of newest event available, in EEN Timestamp format (YYYYMMDDHHMMSS.NNN)
camera_oldest string Timestamp of oldest event available, in EEN Timestamp format (YYYYMMDDHHMMSS.NNN)
camera_info_version int Camera info version
connect string Camera connect status
camera_min_time string Minimum timestamp available, in EEN Timestamp format (YYYYMMDDHHMMSS.NNN)
uuid string UUID string
service string Service status
make string Make of the device
ipaddr string IP Addresses assigned to the device, comma delimited, with the one in use prefixed by an asterisk *
ts string Timestamp in EEN Timestamp format (YYYYMMDDHHMMSS.NNN)
version string Firmware version
status string Status bitmask
mac string MAC address
proxy string Proxy
bridgeid string Device of bridge this device is attached to
now string Current timestamp, in EEN Timestamp format (YYYYMMDDHHMMSS.NNN)
class string Camera, or Bridge, etc.
camera_now string Camera’s current timestamp, in EEN Timestamp format (YYYYMMDDHHMMSS.NNN)
camera_abs_newest string Timestamp of newest event available, in EEN Timestamp format (YYYYMMDDHHMMSS.NNN)
camera_abs_oldest string Timestamp of oldest event available, in EEN Timestamp format (YYYYMMDDHHMMSS.NNN)
model string Device model
esn string ESN id
admin_user string Web Username
admin_password string Web Password

DeviceSettingsRoiNames Attributes

Parameter Data Type Description
roi_id string Object with keys being ROI IDs, and values being the name.

DeviceSettingsAlertNotifications Attributes

Parameter Data Type Description
roi_id array[string] Object with keys being ROI IDs, and values being the array of User IDs

DeviceSettingsAlertModes Attributes

Parameter Data Type Description
roi_id array[string] Object with keys being ROI IDs, and values being the array of alert modes

DeviceSettingsAlertLevels Attributes

Parameter Data Type Description
roi_id array[string] Object with keys being ROI IDs, and values being the array of alert levels

DeviceBridges Attributes

Parameter Data Type Description
device_id string Object with keys being Bridge Device IDs, and values being the service status of the camera on that bridge

Get Camera

Request

curl -G https://login.eagleeyenetworks.com/g/device -d "A=[AUTH_KEY]&id=[CAMERA_ID]"

Returns camera object by id

HTTP Request

GET https://login.eagleeyenetworks.com/g/device

Parameter Data Type Description
id string Camera Id

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges

Add Camera to Bridge

Request

curl --cookie "auth_key=[AUTH_KEY]" -X PUT -v -H "Authentication: [API_KEY]:" -H "content-type: application/json" https://login.eagleeyenetworks.com/g/device -d '{"name":"[NAME]","timezone":[TIMEZONE],"settings":{"bridge":"[BRIDGE_ID]","guid":"[CAMERA_GUID]","username":"","password":""}}'

Json Response

{
  "id": "100c339a"
}

Adds an Unattached Camera to the Bridge

HTTP Request

PUT https://login.eagleeyenetworks.com/g/device

Parameter Data Type Description Is Required
name string Camera Name true
settings DeviceSettings Misc Settings true
timezone string If unspecified, this will default to the camera’s Bridge timezone
tags array[string] Array of strings, which each string representing a “tag”

Response Json Attributes

Parameter Data Type Description
id string Unique identifier for the device
HTTP Status Code Data Type
200 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges
404 No device matching the ConnectID or GUID was found
409 ConnectID or GUID is currently already in use by an account
410 Communication cannot be made to attach the camera to the bridge
415 Device associated with the given GUID is unsupported

Update Camera

Request

curl --cookie "auth_key=[AUTH_KEY]" -X POST -v -H "Authentication: [API_KEY]:" -H "content-type: application/json" https://login.eagleeyenetworks.com/g/device -d '{"id": "[CAMERA_ID], "name": "[NAME]"}'

Json Response

{
  "id": "100c339a"
}

HTTP Request

POST https://login.eagleeyenetworks.com/g/device

Parameter Data Type Description Is Required
id string Camera Id true
name string Camera Name
timezone strings If unspecified, this will default to the camera’s Bridge timezone
tags array[string] Array of strings, which each string representing a “tag”
settings json Misc Settings
camera_parameters_add json JSON object of camera parameters/settings to add/update
camera_parameters_delete json JSON object of camera parameters/settings to delete

Response Json Attributes

Parameter Data Type Description
id string Unique identifier for the device

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges
404 Device matching the ID was not found
463 Unable to communicate with the camera to add/delete camera settings, contact support

Delete Camera

Request

curl --cookie "auth_key=[AUTH_KEY]" -X DELETE -v -H "Authentication: [API_KEY]:" -H "content-type: application/json" https://login.eagleeyenetworks.com/g/device -d "id=[CAMERA_ID]" -G

HTTP Request

DELETE https://login.eagleeyenetworks.com/g/device

Parameter Data Type Description
id string Camera Id

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges
404 Device matching the ID was not found
463 Unable to communicate with the camera or bridge, contact support

Get List of Cameras

Request

curl --cookie "auth_key=[AUTH_KEY]" --request GET https://login.eagleeyenetworks.com/g/device/list

Json Response

[
    [
        "00004206",
        "100d88a8",
        "Main",
        "bridge",
        [
            [
                "100f2fa1",
                "ATTD"
            ],
            [
                "100c339a",
                "ATTD"
            ]
        ],
        "ATTD",
        "swr",
        [],
        "bceb04ec-8b24-4aee-a09a-8479d856e81c",
        "EEN-BR300-08480",
        1048576,
        "US/Pacific",
        -25200,
        1,
        "",
        0,
        "Greater Good",
        false,
        null,
        null,
        [
            null,
            null,
            null,
            null,
            null,
            null
        ]
    ],
    [
        "00004206",
        "100c339a",
        "New Camera 1",
        "camera",
        [
            [
                "100d88a8",
                "ATTD"
            ]
        ],
        "ATTD",
        "swr",
        [],
        "1e574020-4e33-11e3-9b40-2504532f70b4",
        "4242325013460008",
        1441847,
        "US/Pacific",
        -25200,
        0,
        "*10.143.14.254",
        0,
        "Greater Good",
        false,
        null,
        null,
        [
            null,
            null,
            null,
            null,
            null,
            null
        ]
    ],
    [...],
    [...],
    [...]
]

Returns array of arrays, with each sub-array representing a device available to the user. The 'service_status’ attribute either be set to 'ATTD’ or 'IGND’. If the service_status is 'ATTD’, the camera is attached to a bridge. If the service_status is 'IGND’, the camera is unattached from any bridge and is available to be attached. Please note that the ListDevice model definition below has property keys, but that’s only for reference purposes since it’s actually just a standard array.

HTTP Request

GET https://login.eagleeyenetworks.com/g/device/list

Parameter Data Type Description
e string Camera Id
n string Camera Name
t string Device Type
s string Device Service Status

Response: Camera Model

Array Index Attribute Data Type Description
0 account_id string Unique identifier for the Device’s Account
1 id string Unique identifier for the Device
2 name string Name of the device
3 type string, enum Type of device

enum: camera, bridge
4 bridges array[array[string]] This is an array of string arrays, each string array represents a bridge that can see the camera. The first element of the string array is the bridge ESN. The second element is the status.
5 service_status string, enum Device service status. ATTD = camera is attached to a bridge. IGND = camera is unattached from all bridges and is available to be attached to a bridge.

enum: ATTD, IGND
6 permissions string String of zero or more characters. Each character defines a permission that the current user has for the device. Permissions include: 'R’ - user can view this device. 'W’ - user can modify and delete this device. ’S’ - user can share this device.
7 tags array[string] Tags
8 guid string GUID
9 serial_number string Serial number
10 device_status int Device status bit mask
11 timezone string Timezone
12 timezone_utc_offset int Timezone UTC offset as signed integer in seconds, such as “-25200”, which translates to -7 hours from UTC.
13 is_unsupported int Indicates the camera is NOT supported (1) or IS supported (0)
14 ip_address string IP Address of device
15 is_shared int Indicates the camera is shared (1) or not (0)
16 owner_account_name string Name of the account that owns the device. This only applies to shared cameras, since they will be owned by a different account.
17 is_upnp boolean Indicates whether the camera is a UPNP device. Note that this property is different then all the other 'is_*’ properties in the API, which normally are integers (0 or 1). Currently this property only applies to cameras that haven’t yet been attached to the account, in which they could have been detected via ONVIF or UPNP.
18 video_input string For analog cameras only, this indicates the video input channel of the camera.
19 video_status string For analog cameras only, this indicates the video status of the camera.

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges

Bridge

Overview

The Bridge is a product of Eagle Eye that sits at the customer location and talks to industry standard cameras. It converts the Cameras to be compatible with the EEVB and record the Assets. The Bridge is setup and controlled via a cloud based user inteface. There is no user interface on the Bridge. The Bridge may serve local Assets directly to local Clients. The Bridge will also store Assets until they are transferred to the EEVB. The Bridge may be configured via DHCP or with a static IP address.

Get Bridge

Request

curl -G https://login.eagleeyenetworks.com/g/device -d "A=[AUTH_KEY]&id=[BRIDGE_ID]"

Json Response

{
    "bridges": null,
    "camera_info_status_code": 404,
    "name": "Main",
    "settings": {
        "bridge": null,
        "is_logically_deleted": false
    },
    "camera_settings_status_code": 200,
    "camera_info": null,
    "utcOffset": -25200,
    "camera_parameters_status_code": 200,
    "id": "100d88a8",
    "timezone": "US/Pacific",
    "guid": "bceb04ec-8b24-4aee-a09a-8479d856e81c",
    "camera_parameters": {
        "active_settings": {
            "max_disk_usage": {
                "max": 0.97999999999999998,
                "min": 0.050000000000000003,
                "d": 0.80000000000000004,
                "v": 0.80000000000000004
            },
            "display_layouts": {
                "d": {},
                "v": {}
            },
            "local_display_enable": {
                "max": 1,
                "min": 0,
                "d": 0,
                "v": 0
            },
            "bandwidth_background": {
                "max": 10000000000.0,
                "min": -1000.0,
                "d": 100000.0,
                "v": 100000.0
            },
            "bandwidth_recover": {
                "max": 10000000000.0,
                "min": 100000.0,
                "d": 5000000.0,
                "v": 5000000.0
            },
            "stream_stats_present_only": {
                "max": 1,
                "min": 0,
                "d": 1,
                "v": 1
            },
            "retention_days": {
                "max": 10000,
                "min": 1,
                "d": 14,
                "v": 14
            },
            "bridge_retention_days": {
                "max": 100000,
                "min": 0,
                "d": 0,
                "v": 0
            },
            "stream_stats": {
                "d": "none",
                "v": "none"
            },
            "upnp_enable": {
                "max": 1,
                "min": -1,
                "d": 0,
                "v": 0
            },
            "bandwidth_demand": {
                "max": 10000000000.0,
                "min": 100000.0,
                "d": 10000000.0,
                "v": 10000000.0
            },
            "bandwidth_upload": {
                "max": 10000000000.0,
                "min": 100000.0,
                "d": 1000000.0,
                "v": 1000000.0
            },
            "retention_priority": {
                "max": 10000,
                "min": 1,
                "d": 100,
                "v": 100
            },
            "display_default_enabled": {
                "max": 1,
                "min": 0,
                "d": 1,
                "v": 1
            }
        },
        "active_filters": [
            "schedule_bandwidth_background",
            "user_user"
        ],
        "user_settings": {
            "versions": {},
            "settings": {
                "upnp_enable": "0",
                "bandwidth_background": 50000
            },
            "schedules": {
                "bandwidth_background": {
                    "priority": 1,
                    "start": {
                        "seconds": 0,
                        "hours": 8,
                        "months": "*",
                        "minutes": 0,
                        "wdays": [
                            1,
                            2,
                            3,
                            4,
                            5,
                            6,
                            7
                        ]
                    },
                    "end": {
                        "seconds": 0,
                        "hours": 17,
                        "months": "*",
                        "minutes": 30,
                        "wdays": [
                            1,
                            2,
                            3,
                            4,
                            5,
                            6,
                            7
                        ]
                    },
                    "when": "work",
                    "settings": {
                        "bandwidth_background": "100000"
                    }
                }
            }
        }
    },
    "tags": [],
    "permissions": "swr"
  }

Returns bridge object by id.

HTTP Request

GET https://login.eagleeyenetworks.com/g/device

Parameter Data Type Description Is Required
id string Bridge Id true

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges

Add Bridge to EEVB

Request

curl --cookie "auth_key=[AUTH_KEY]" -X PUT -v -H "Authentication: [API_KEY]:" -H "content-type: application/json" https://login.eagleeyenetworks.com/g/device -d '{"name":"[NAME]","connectID":[CONNECT_ID]}'

Json Response

{
  "id": "100c339a"
}

Adds a bridge to the Eagle Eye Video Bank

HTTP Request

PUT https://login.eagleeyenetworks.com/g/device

Parameter Data Type Description
name string Bridge Name
connectID string Connect ID is needed to add and activate bridge to account. All non-alphanumeric characters will be stripped.

Response Json Attributes

Parameter Data Type Description
id string Unique identifier for the device

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges
404 No device matching the ConnectID or GUID was found
409 ConnectID or GUID is currently already in use by an account
410 Communication cannot be made to attach the camera to the bridge
415 Device associated with the given GUID is unsupported

Update Bridge

Request

curl --cookie "auth_key=[AUTH_KEY]" -X POST -v -H "Authentication: [API_KEY]:" -H "content-type: application/json" https://login.eagleeyenetworks.com/g/device -d '{"id": "[BRIDGE_ID], "name": "[NAME]"}'

Json Response

{
  "id": "100c339a"
}

HTTP Request

POST https://login.eagleeyenetworks.com/g/device

Parameter Data Type Description Is Required
id string Bridge Id true
name string Bridge Name
timezone string Timezone of the bridge. Defaults to ‘US/Pacific’. Possible values: 'US/Alaska’ or 'US/Arizona’ or 'US/Central’ or 'US/Eastern’ or 'US/Hawaii’ or 'America/Anchorage’ or 'UTC’
tags array[string] Array of strings, which each string representing a “tag”
settings json Misc Settings
camera_parameters_add json JSON object of camera parameters/settings to add/update
camera_parameters_delete json JSON object of camera parameters/settings to delete

Response Json Attributes

Parameter Data Type Description
id string Unique identifier for the device

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges
404 Device matching the ID was not found
463 Unable to communicate with the camera to add/delete camera settings, contact support

Delete Bridge

Request

curl --cookie "auth_key=[AUTH_KEY]" -X DELETE -v -H "Authentication: [API_KEY]:" -H "content-type: application/json" https://login.eagleeyenetworks.com/g/device -d "id=[BRIDGE_ID]" -G

HTTP Request

DELETE https://login.eagleeyenetworks.com/g/device

Parameter Data Type Description
id string Bridge Id

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges
404 Device matching the ID was not found
463 Unable to communicate with the camera or bridge, contact support

Get List of Bridges

Request

curl --cookie "auth_key=[AUTH_KEY]" --request GET https://login.eagleeyenetworks.com/g/device/list

Json Response

[
    [
        "00004206",
        "100d88a8",
        "Main",
        "bridge",
        [
            [
                "100f2fa1",
                "ATTD"
            ],
            [
                "100c339a",
                "ATTD"
            ]
        ],
        "ATTD",
        "swr",
        [],
        "bceb04ec-8b24-4aee-a09a-8479d856e81c",
        "EEN-BR300-08480",
        1048576,
        "US/Pacific",
        -25200,
        1,
        "",
        0,
        "Greater Good",
        false,
        null,
        null,
        [
            null,
            null,
            null,
            null,
            null,
            null
        ]
    ],
    [
        "00004206",
        "100c339a",
        "New Camera 1",
        "camera",
        [
            [
                "100d88a8",
                "ATTD"
            ]
        ],
        "ATTD",
        "swr",
        [],
        "1e574020-4e33-11e3-9b40-2504532f70b4",
        "4242325013460008",
        1441847,
        "US/Pacific",
        -25200,
        0,
        "*10.143.14.254",
        0,
        "Greater Good",
        false,
        null,
        null,
        [
            null,
            null,
            null,
            null,
            null,
            null
        ]
    ],
    [
        "00004206",
        "100f2fa1",
        "Dome",
        "camera",
        [
            [
                "100d88a8",
                "ATTD"
            ]
        ],
        "ATTD",
        "swr",
        [],
        "3b3efd60-432d-11e3-b19b-11ac28dbc101",
        "4016825013440034",
        1441847,
        "US/Pacific",
        -25200,
        0,
        "*10.143.217.117",
        0,
        "Greater Good",
        false,
        null,
        null,
        [
            null,
            null,
            null,
            null,
            "",
            null
        ]
    ]
]

Returns array of arrays, with each sub-array representing a device available to the user. The 'service_status’ attribute either be set to 'ATTD’ or 'IGND’. If the service_status is 'ATTD’, the camera is attached to a bridge. If the service_status is 'IGND’, the camera is unattached from any bridge and is available to be attached. Please note that the ListDevice model definition below has property keys, but that’s only for reference purposes since it’s actually just a standard array.

HTTP Request

GET https://login.eagleeyenetworks.com/g/device/list

Parameter Data Type Description
e string Bridge Id
n string Bridge Name
t string Device Type
s string Device Service Status

Response: Bridge Model

Array Index Attribute Data Type
0 account_id string
1 id string
2 name string
3 type string
4 bridges json
5 service_status string
6 permissions string
7 tags array[string]
8 guid string
9 serial_number string
10 device_status int
11 timezone string
12 timezone_utc_offset int
13 is_unsupported int
14 ip_address string
15 is_shared int
16 owner_account_name string
17 is_upnp boolean
18 video_input string
19 video_status string

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges

Images and Video

Overview

Asset services provide access to media assets - previews and video in appropriate formats. Asset services are used in conjunction with list transactions to enumerate and identify assets.

Assets are identified by a tuple of timestamp, cameraid, quality, and format.

Request Image

The image request model provides an efficient mechanism for accessing image sequences for several usage models. Image requests can be done directly using the next/after/prev virtual model. This returns images before or after specified timestamps. Alternatively, the timestamp and event information can be fetched through the “list” interface (to get events for history) and “poll” interface to track new images as they become available in real-time. The following cookbooks provides typical usage models for various events.

Retrieve List of Images

There are a couple different ways to get a list of images. There first is to get all preview images between April 1st and April 2nd: https://login.eagleeyenetworks.com/asset/list/image.jpeg?c=100676b2;t=20140401000000.000;e=20140402000000.000;a=all;

The second way is to get 500 images before April 1st: https://login.eagleeyenetworks.com/asset/list/image.jpeg?c=100676b2;t=20140401000000.000;count=-500;a=all;

The third way is to get the next 500 images after April 1st: https://login.eagleeyenetworks.com/asset/list/image.jpeg?c=100676b2;t=20140401000000.000;count=500;a=all;

Retrieve Video

Video is accessed via the “play” command. Video is captured in segments, and is limited to 5 minutes per segment in storage. The video command will seamlessly rewrite headers within the video format to join segments as necessary to deliver the requested data span. However, we highly encourage developers to fetch only 5 minutes at a time to ensure that users aren’t filling storage on their bridge needlessly.

If the end time of the segment is in the future, the video will follow the data stream as it arrives, delivering live video streaming with minimal latency. MP4 format cannot be live streamed. Note: if the camera is not streaming video, the video will stop (and start again) as video is captured, which is typically not what is desired.

The key word “stream_” can be used for the starting timestamp. This forces the camera to capture video and stream it to the cloud live. The stream id should be globally unique(ish) string - combination of a timestamp and userid works well. It is only critical for M3U requests, where it assure continuity between the m3u poll transactions.

The start timestamp must match the starting timestamp of a video if the video already exists. Subsegments of a video span can be specified by using the “to” (time offset) argument. For example, assume a 5 minute video has been recorded from 12:30 to 12:35. The query “?t=20121120123000.000;e=20121120123400.000;to=180000;…” will play one minute of video (timestamped at 12:33), 3 minutes into the video starting at 12:30, clipping off the last minute of the recorded segment.

Time offsets and end timestamps can be at any time, but the system will seek to the nearest key frame to actually start the video.

Video Formats

The video system is based on h264 video and AAC audio. These streams are encapsulated in different formats for compatibility with different playback modes

Note: If you choose to stream any video format on the web other than FLV (Our native format as mentioned above), you may initially get a 502 response. This means that the video is currently being transcoded within our system and therefore couldn’t be found. Assuming the data actually exists (check against the video list call), the video will eventually be ready for you to fetch in the desired format, but, for the time being, you will have to wait and refetch until the requested video is ready.

Video Quality

The H264 codec has the concept of profiles and levels to convey whether a playback devices is compatible with a specific video stream.

EEN Timestamp

All Assets have an EEN timestamp attached. Timestamps are always in UTC and maintained to the nearest millisecond. Timestamps are rendered in text as YYYYMMDDhhmmss.mmm.

+/- offsets from “now” are valid in ms.

Get Image

Request

curl -v -G "https://login.eagleeyenetworks.com/asset/prev/image.jpeg?id=[CAMERA_ID];timestamp=[TIMESTAMP];asset_class=[ASSET_CLASS];A=[AUTH_KEY]"

Get an image jpeg based on the specified timestamp. This will return binary image data in JPEG format.

Headers: cache control headers to allow asset caching if no now relative:

HTTP Request

GET https://login.eagleeyenetworks.com/asset/asset/image.jpeg
Get the image at the specified timestamp

GET https://login.eagleeyenetworks.com/asset/prev/image.jpeg
Get the first image before the specified timestamp

GET https://login.eagleeyenetworks.com/asset/after/image.jpeg
Get the first image after the specified timestamp

Parameter Data Type Description Is Required
id string Camera Id true
timestamp string Timestamp in EEN format: YYYYMMDDHHMMSS.NNN true
asset_class string, enum Asset class of the image

enum: all, pre, thumb
true
quality string, enum Future Feature: Quality of image

enum: low, med, high

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
301 Asset has been moved to a different archiver
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges
404 Image was not found

Get Video

Request

curl -v -G "https://login.eagleeyenetworks.com/asset/play/video.flv?id=[CAMERA_ID];start_timestamp=[START_TIMESTAMP];end_timestamp=[END_TIMESTAMP];A=[AUTH_KEY]"

Returns a video stream in the requested format. Formats include

HTTP Request

GET https://login.eagleeyenetworks.com/asset/play/video.{video_format}

Parameter Data Type Description Is Required
id string Camera Id true
start_timestamp string Start Timestamp in EEN format: YYYYMMDDHHMMSS.NNN true
end_timestamp string End Timestamp in EEN format: YYYYMMDDHHMMSS.NNN true
quality string, enum Future Feature: Indicates requested resolution if multiple are available.

enum: low, mid, high

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
301 Asset has been moved to a different archiver
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges
404 Camera not provisioned
404 Camera get error
410 Video is out of retention
503 Camera tag maps not loaded

Prefetch Image

Request

curl -v -G "https://login.eagleeyenetworks.com/asset/cloud/image.jpg?start_timestamp=[START_TIMESTAMP];id=[CAMERA_ID];webhook_url=[WEBHOOK_URL]A=[AUTH_KEY]"

Webhook JSON POST Response

{ "event:": "[EVENT]" }

This API call will ensure the image is in the cloud. If the image is not in the cloud it will do a background upload request to the bridge to aquire the image into the cloud. A webhook provided with the call will be triggered when the upload is successful or an error has occurred. The webhook will be triggered as a POST with JSON formatted data.

HTTP Request

GET https://login.eagleeyenetworks.com/asset/cloud/image.jpg

Parameter Data Type Description Is Required
id string Camera Id true
start_timestamp string Start Timestamp in EEN format: YYYYMMDDHHMMSS.NNN true
webhook_url string The webhook url (must be urlencoded) to trigger true

JSON EVENT Values

Value Description
ASSET_CLOUD_EVENT_UPLOADED The image has been successfully uploaded into the cloud.
ASSET_CLOUD_EVENT_DEMAND_FAILED The image failed aquiring a connection to the bridge.
ASSET_CLOUD_EVENT_NOTHING_UPLOAD Nothing was uploaded since the image was already in the cloud.
ASSET_CLOUD_EVENT_INVALID_RANGE An invalid range (timestamp) was requested.
ASSET_CLOUD_EVENT_ABORT General error occurred.

HTTP Status Codes

HTTP Status Code Data Type
201 Request has been created and webhook will be triggered upon completion or error.

Prefetch Video

Request

curl -v -G "https://login.eagleeyenetworks.com/asset/cloud/video.flv?start_timestamp=[START_TIMESTAMP];end_timestamp=[END_TIMESTAMP];id=[CAMERA_ID];webhook_url=[WEBHOOK_URL]A=[AUTH_KEY]"

Webhook JSON POST Response

{ "event:": "[EVENT]" }

This API call will ensure the video is in the cloud. If the video is not in the cloud it will do a background upload request to the bridge to aquire the video into the cloud. A webhook provided with the call will be triggered when the upload is successful or an error has occurred. The webhook will be triggered as a POST with JSON formatted data.

HTTP Request

GET https://login.eagleeyenetworks.com/asset/cloud/video.flv

Parameter Data Type Description Is Required
id string Camera Id true
start_timestamp string Start Timestamp in EEN format: YYYYMMDDHHMMSS.NNN true
end_timestamp string End Timestamp in EEN format: YYYYMMDDHHMMSS.NNN true
webhook_url string The webhook url (must be urlencoded) to trigger true

JSON EVENT Values

Value Description
ASSET_CLOUD_EVENT_UPLOADED The video has been successfully uploaded into the cloud.
ASSET_CLOUD_EVENT_DEMAND_FAILED The video failed aquiring a connection to the bridge.
ASSET_CLOUD_EVENT_NOTHING_UPLOAD Nothing was uploaded since the video was already in the cloud.
ASSET_CLOUD_EVENT_INVALID_RANGE An invalid range (timestamp) was requested.
ASSET_CLOUD_EVENT_ABORT General error occurred.

HTTP Status Codes

HTTP Status Code Data Type
201 Request has been created and webhook will be triggered upon completion or error.

Get List of Images

Request

curl -v -G "https://login.eagleeyenetworks.com/asset/list/image?start_timestamp=[START_TIMESTAMP];end_timestamp=[END_TIMESTAMP];id=[CAMERA_ID];asset_class=[ASSET_CLASS];A=[AUTH_KEY]"

Json Response

[{"t":"PRFR","s":"20141001000000.045"},{"t":"PRFR","s":"20141001000001.045"},{"t":"PRFR","s":"20141001000002.064"},{"t":"PRFR","s":"20141001000003.064"},{"t":"PRFR","s":"20141001000004.064"},{"t":"PRFR","s":"20141001000005.063"},{"t":"PRFR","s":"20141001000006.063"},{"t":"PRFR","s":"20141001000007.096"}]

This returns a list of objects, where each object contains the timestamp and type of an image jpeg. When formatting the request, either the 'end_timestamp’ or 'count’ parameter is required.

HTTP Request

GET https://login.eagleeyenetworks.com/asset/list/image

Parameter Data Type Description Is Required
id string Camera Id true
start_timestamp string Start Timestamp in EEN format: YYYYMMDDHHMMSS.NNN true
asset_class string, enum Asset class of the image

enum: all, pre, thumb
true
end_timestamp string End Timestamp in EEN format: YYYYMMDDHHMMSS.NNN
count int Used instead or with an 'end_timestamp’ argument. If used with an 'end_timestamp’ argument, the count is a limit on the number of entries to return, starting at the starting timestamp. If used without the e argument, returns N entries. Support negative value, which returns N entries before, sorted in reverse order - example -5 return 5 events previous to the specified time.

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
301 Asset has been moved to a different archiver
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges

Get List of Videos

Request

curl -v -G "https://login.eagleeyenetworks.com/asset/list/video?start_timestamp=[START_TIMESTAMP];end_timestamp=[END_TIMESTAMP];id=[CAMERA_ID];options=coalesce;A=[AUTH_KEY]"

Json Response

[{"s":"20141001000016.768","e":"20141001000100.758"},{"s":"20141001000220.825","e":"20141001000242.774"},{"s":"20141001000256.811","e":"20141001000320.869"},{"s":"20141001000354.761","e":"20141001000422.812"},{"s":"20141001000526.821","e":"20141001000632.829"},{"s":"20141001000746.836","e":"20141001000834.757"},{"s":"20141001000904.749","e":"20141001000932.767"},{"s":"20141001000934.766","e":"20141001001002.777"}]

This returns a list of objects, where each object contains the start and end timestamp of a single video clip. When formatting the request, either the 'end_timestamp’ or 'count’ parameter is required.

HTTP Request

GET https://login.eagleeyenetworks.com/asset/list/video

Parameter Data Type Description Is Required
id string Camera Id true
start_timestamp string Start Timestamp in EEN format: YYYYMMDDHHMMSS.NNN true
end_timestamp string End Timestamp in EEN format: YYYYMMDDHHMMSS.NNN
count int Used instead or with an 'end_timestamp’ argument. If used with an 'end_timestamp’ argument, the count is a limit on the number of entries to return, starting at the starting timestamp. If used without the e argument, returns N entries. Support negative value, which returns N entries before, sorted in reverse order - example -5 return 5 events previous to the specified time.
options string, enum Additional modifier options. 'coalesce’ = coalesces spans together.

enum: coalesce

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
301 Asset has been moved to a different archiver
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges

Poll

Overview

The poll service provides a mechanism for an application to receive notifications of events or spans from the Eagle Eye service. These entities are grouped by resource. There are five main resources:

Events can come from lots of sources:

Device and Camera events include, on, off, online, offline, currently recording, currently sensing motion, start/stop schedule event, being controlled with PTZ)

This service will continually be extended.

Poll is a stateful request for updates any time a matching event occurs within the service. The initial poll request is a POST (Default GET with WebSocket) with a JSON formatted body indicating the resources to track. Resources that are video, pre, and thumbnail automatically register the API caller to their respective events. However, resource type ‘event’ requires the API caller to tell the API what events to listen for.

Each object consists of an id element and a list of resource types to be monitored. The POST transaction receives and immediately responds with a JSON formatted body indicating the current timestamp for all requested resources. The response also includes a cookie, which can be used to track changes to the indicated resources via GET transaction.

Each resource type has a specific object format in response:

Type Response Notes
video [startts, endts] List of start, end Timestamps for video segment. Updates at start and per key frame received until end.
thumb thumbts Timestamp of latest thumbnail image
pre prets Timestamp of latest preview image
status bitmask A numerical bitmask defining the status. Bit position defines status. The meaning of each bit is defined in the table below.
event object Events are a key value pair, where the key is the four CC of the event, and event structure are the actual meta data for that specific event. Available events are shown in the table below.

Status Bitmask

HEX Value Status
0x000001 Camera Online (DEPRECATED)
0x000002 Stream Attached (Camera Communicating With Bridge) (DEPRECATED)
0x000004 Camera On (User Setting) (DEPRECATED)
0x000008 Camera Recording (DEPRECATED)
0x000010 Camera Sending Previews
0x000020 Camera Located (Bridge has found the camera)
0x000040 Camera Not Supported
0x000080 Camera Configuration in Process (Bridge Configuring Camera)
0x000100 Camera Needs ONVIF Password
0x000200 Camera Available But Not Yet Attached
0x000400 Internal Status
0x000800 Camera Error
0x001000 Internal Status
0x002000 Internal Status
0x004000 Reserved
0x008000 Reserved
0x010000 Invalid State (Unknown State)
0x020000 Camera On (User Setting)
0x040000 Camera Streaming Video
0x080000 Camera Recording
0x100000 Camera Online

This status bit mask is used to determine what the high-level/overall camera status is, using the following logic:

IF “Camera On” (bit 17)==0 THEN “Off” (orange forbidden icon)
ELSE IF “Registered” (bit 20)==0 THEN “Internet Offline” (red exclamation icon)
ELSE IF “Streaming” (bit 18)==1 THEN “Online” (green check icon)
ELSE IF “Password” (bit 8)==1 THEN “Password Needed” (effectively “Offline”) (red padlock icon)
ELSE “Offline” (red X icon)

Recording status uses the following logic:

IF “Recording” (bit 19) THEN Recording (green circle icon)

IF “Invalid” (bit 16)==1 THEN no status change (use whatever status bits were set previously)

Event Objects

Four CC Description
VRES Video start event
VREE Video end event
VRKF Video key frame event
VRSU Video update event
PRSS Preview stream start event
PRTH Thumbnail event
PRFR Preview event
PRSE Preview stream end event
PRSU Preview stream update event
EMES Motion start event
EMEE Motion end event
ESES Event stream start
EVVS Video swap event
ESEE Event stream stop
ECON The camera is online
ECOF The camera is offline
AELI Account event log in
AELO Account event log out
AEDO Download video event
AEUC Create user event
AEUD Delete user event
AECC User config change event
AELD Live display event
AEPT Pan tilt zoom event
AAEC Layout create event
AEED Layout delete event
AEEL Layout change event
AEAC Account create event
AEAD Account delete event
AEAH Account change event
AEDC Device create event
AEDD Device delete event
AEDH Device change event
CECF Camera found event
CSAT Camera stream attach event
CSDT Camera stream detach event
COFF Camera off event
CONN Camera on event
COBC Camera bounce event
CSTS Camera settings event
CSTC Camera settings change event
CPRG Camera purge event
CDLT Camera data lost event
CBWS Camera bandwidth sample event
BBWS Bridge bandwidth sample event
AEDA Device alert event
AEDN Device alert notification event
MRBX Motion Box event
MRSZ Motion size reports
ROMS Region of interest motion start
ROME Region of interest motion end
ALMS Alert Motion Start
ALME Alert Motion End
ALRS Alert Region Of Interest Start
ALRE Alert Region Of Interest End

Initialize Poll

Request Json

{
    "cameras": {
        "100e1e23": {
            "resource": [
                "pre",
                "thumb",
                "status",
                "event"
            ],
            "event": [
                "MRBX"
            ]
        },
        "10097d15": {
            "resource": [
                "pre",
                "thumb",
                "status",
                "event"
            ],
            "event": [
                "MRBX"
            ]
        },
        "<camera_id>": {...},
        "<camera_id>": {...},
        "<camera_id>": {...}
    }
}

Subscribe to poll service, which is required for GET /poll. Response headers: set_cookie: ee-poll-ses=xxxxxx

HTTP Request

POST https://login.eagleeyenetworks.com/poll

Parameter Data Type Description
cameras PostPollCameras Cameras

PostPollCameras Attributes

Parameter Data Type Description
PostPollCamera camera_id holding the data structure for the camera

PostPollCamera Attributes

Parameter Data Type Description
resource array[string, enum] enum: pre, thumb, status, event
event array[string, enum] enum: event objects

Json Response

{
    "cameras": {
        "100e1e23": {
            "status": 1441847
        },
        "10097d15": {
            "status": 1441847
        },
        "<camera_id>": {...},
        "<camera_id>": {...},
        "<camera_id>": {...}
    },
    "token": "ooe0eoEAMNsF"
}

Response Json Attributes

Parameter Data Type Description
cameras PostPollResponseCameras Objects keyed by camera id
token string Token to be used for subsequent GET /poll requests

PostPollResponseCameras Json Attributes

Parameter Data Type Description
PostPollResponseCamera PostPollResponse keyed on camera_id

PostPollResponseCamera Json Attributes

Parameter Data Type Description
status string A bitmask flag defining the state of a bridge or a camera. More Info
event PostPollResponseCameraEvents Object of events keyed by event id

PostPollResponseCameraEvents Json Attributes

Parameter Data Type Description
PostPollResponseCameraEvent PostPollResponseCameraEvent keyed on event_id

PostPollResponseCameraEvent Json Attributes

Parameter Data Type Description
timestamp string Timestamp in EEN format: YYYYMMDDHHMMSS.NNN
cameraid string Internal unique identifier

Polling

Used to receive updates on real-time changes. This API call requires a valid ‘ee-poll-ses’ cookie from POST /poll.

HTTP Request

Request

GET https://login.eagleeyenetworks.com/poll

Json Response

{
    "cameras": {
        "100e1e23": {
            "pre": "20141121165011.233",
            "event": {
                "MRBX": {
                    "timestamp": "20141121165011.499",
                    "cameraid": "100c299e",
                    "boxes": [
                        {
                            "x": 24575,
                            "y": 29126,
                            "w": 4095,
                            "h": 5825
                        }
                    ]
                },
                "PRFU": {
                    "timestamp": "20141121165011.233",
                    "cameraid": "100c299e",
                    "file_offset": 26311872,
                    "frame_size": 7838
                },
                "PRFR": {
                    "timestamp": "20141121165011.233",
                    "cameraid": "100c299e",
                    "previewid": 1416585600,
                    "file_offset": 26311872,
                    "frame_size": 7830
                }
            }
        },
        "10097d15": {
            "pre": "20141121165011.281",
            "event": {
                "PRFU": {
                    "timestamp": "20141121165011.281",
                    "cameraid": "1002a2a4",
                    "file_offset": 6126297,
                    "frame_size": 4014
                },
                "PRFR": {
                    "timestamp": "20141121165011.281",
                    "cameraid": "1002a2a4",
                    "previewid": 1416585600,
                    "file_offset": 6126297,
                    "frame_size": 4006
                }
            }
        }
    }
}

Response Json Attributes

Parameter Data Type Description
cameras GetPollResponseCameras Objects keyed by camera id

GetPollResponseCameras Json Attributes

Parameter Data Type Description
GetPollResponseCamera GetPollResponseCamera keyed on camera_id

GetPollResponseCamera Json Attributes

Parameter Data Type Description
pre string Timestamp in EEN format: YYYYMMDDHHMMSS.NNN
event GetPollResponseCameraEvents Object of events keyed by event id

GetPollResponseCameraEvents Json Attributes

Parameter Data Type Description
GetPollResponseCameraEvent GetPollResponseCameraEvent keyed on event_id

GetPollResponseCameraEvent Json Attributes

Parameter Data Type Description
timestamp string Timestamp in EEN format: YYYYMMDDHHMMSS.NNN
cameraid string internal unique identifier

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges

WebSocket Polling

Request Json

{
    "cameras": {
        "100e1e23": {
            "resource": [
                "pre",
                "thumb",
                "status",
                "event"
            ],
            "event": [
                "MRBX"
            ]
        },
        "10097d15": {
            "resource": [
                "pre",
                "thumb",
                "status",
                "event"
            ],
            "event": [
                "MRBX"
            ]
        },
        "<camera_id>": {...},
        "<camera_id>": {...},
        "<camera_id>": {...}
    }
}

WebSockets provide a persistent connection between a client and server. This uplink enables a two-way data stream over which chunked data can be sent and received as messages. This protocol provides a full-duplex communications channel over a single TCP connection, allowing the client to receive event-driven responses without having to poll the server for a reply (effectively decreasing data traffic)

The WebSocket similarity to the HTTP protocol is that its handshake is interpreted by HTTP servers as an 'upgrade request’

Client Handshake Request

GET /api/v2/Device/00001007/Events HTTP/1.1
Upgrade: websocket
Connection: Upgrade
Host: c000.eagleeyenetworks.com
Origin: http://c000.eagleeyenetworks.com
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13
Cookie: auth_key=[AUTH_KEY]

The WebSocket protocol has two parts:

The handshake process has to be initiated from the client side via a standard HTTP request (the HTTP version must be 1.1 or greater and the method must be GET)

The WebSocket request URL is composed in the following way:
wss:// c000. eagleeyenetworks.com /api/v2 /Device /00001007 /Events
secure
websocket
protocol
branded
subdomain
server API version resource account ID 'Events’ suffix

WebSocket URLs use the WS scheme or alternatively WSS for secure connections which is the equivalent of HTTPS

Parameter Data Type Description Is Required
A string Used to replace the 'auth_key’ cookie false

Server Handshake Response

HTTP/1.1 101 Switching Protocols
Server: openresty
Date: Wed, 08 Mar 2018 14:01:06 GMT
Connection: upgrade
upgrade: websocket
sec-websocket-accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
set-cookie: ee-ws-poll-ses=kjxZXVrDyIkK
x-een-lb-tried-proxies: 209.94.238.21:80

The server reply completes the handshake. A successful server reply is followed by data transfer

Error Status Codes

Status Code Description
400 Header is not understood or has an incorrect value
101 Switching Protocols

Data Exchange

The client communicates with the server after a successful handshake by sending an object as Json-formatted string. The 'message’ send is being triggered by the client by calling the appropriate WebSocket 'send’ function (the method depends on the client environment)

The client has to specify via Json what kind of data it is going to be polling and from which devices. See Initialize Poll, Resource Type, Event Objects

WebSocket is an event-driven API. When messages are received a message event is delivered to the the 'onmessage’ function, where the message is being received and parsed

The connection can be severed at any given time using the 'close’ function

A successful handshake can be established even with an incorrect data set in the Json-formatted string. This action will however yield 'message’ response error codes for each individual encountered problem based on the Errors section

Message Error Status Codes

Status Code Description
400 Invalid Resource
401 Access Denied
412 Auth Lost
200 OK

Layout

Overview

Layouts contain panes, which is a group of cameras arranged for viewing on screen. Layouts are associated with an account and account users are granted view/write/share permissions for the layout. Users who would otherwise have no access to a camera gain access to all cameras included in layouts shared with them.

The ordering of the panes is determined by the order of the array of LayoutJsonPane returned by the API. Each pane will have a size of 1, 2, or 3. A size of 1 is the smallest, and fills up 1x1 on the layout grid. A size of 3 is the largest and fills up 3x3 on the layout grid. If the grid does not have enough columns to fit the pane, then the size of the pane is decreased until it is able to fit on the grid.

Rendered Layouts on Web and Mobile: Example 1 Example 2

Layout Model

Layout Model

{
    "id": "0b58ec7a-61e4-11e3-8f7d-523445989f37",
    "name": "Everything",
    "types": [
        "mobile"
    ],
    "permissions": "SWRD",
    "current_recording_key": null,
    "shares": [
        [
            "ca01ce6d",
            "SWRD"
        ],
        [
            "ca0c7d2c",
            "R"
        ],
        [...],
        [...],
        [...],
        [
            "ca05e8c2",
            "R"
        ]
    ],
    "configuration": {
        "panes": [
            {
                "cameras": [
                    "100ace90"
                ],
                "type": "preview",
                "pane_id": 0,
                "name": "",
                "size": 1
            },
            {
                "cameras": [
                    "10045dd6"
                ],
                "type": "preview",
                "pane_id": 0,
                "name": "",
                "size": 1
            },
            {...},
            {...},
            {...},
            {
                "cameras": [
                    "100891b7"
                ],
                "type": "preview",
                "pane_id": 0,
                "name": "",
                "size": 1
            }
        ],
        "settings": {
            "camera_row_limit": 3,
            "camera_name": true,
            "camera_aspect_ratio": 0.5625,
            "camera_border": false
        }
    }
}

Layout Attributes

Property Data Type Description Editable Required
id string Unique identifier for the Layout false GET, POST, PUT, DELETE
name string Name of the layout true PUT
types array[string] Specifies target(s) for layout. Multiple values are allowed. true PUT
permissions string String of zero or more characters. Each character defines a permission. Permissions include: ‘R’ - user can view this layout. 'W’ - user can modify this layout. ’D’ - user can delete this layout. ’S’ - user can share this layout false
current_recording_key string String key representing a recording currently being made with the cameras in the layout, which was initiated using the action/recordnow service. false
shares array[array[string]]) Array of arrays, one per account user for whom sharing is enabled for this layout. Each string contains two field separated by comma. The first field is a user aid and the second field are permissions for the user. Two special user ID exist: ‘account’ specifies that the layout is shared with all users of the account. Second field contains permissions for users in the account. Example: [‘cafedead’,’RWDS’] = user can view, change, delete or share this layout. [‘cafe0001’,’RW’] = user can view this layout and change this layout. [‘account’, ‘R’] = All users of the account can view this layout. Permissions for the user issuing the /layout GET are not included in this array. false
configuration LayoutConfiguration JSON object that defines the layout configuration true

LayoutConfiguration Attributes

Parameter Data Type Description
panes array[LayoutConfigurationPane] Array of Panes
settings LayoutConfigurationSettings Settings object

LayoutConfigurationPane Attributes

Parameter Data Type Description
name string Layout pane name
type string ‘preview’ - shows live preview images form cameras. ‘carousel’- rotates between preview images, ids of cameras needs to be include in the cameras array along with an integer in the delay array. The delay is an integer value of milliseconds as too how long the Camera will be displayed before switching to the next Camera. A “carousel” with only one camera is the same as preview. ‘click’ - respond to click for other cameras in layout. ‘motion’ - respond to motion for other cameras in layout. ‘map’ - a static map with camera icons located on it. ‘url’ - displays the contents of the url in the pane as a frame.
pane_id int ID given to pane when created from Layout Manager
size int ['1’ or '2’ or '3’]: Size to display image: 1 = small, 2 = medium, 3 = large
cameras array[string] )Array of camera ids. For ‘carousel’, cycle through the camera ids with the delay setting in the corresponding ‘delay’ property

LayoutConfigurationSettings Attributes

Parameter Data Type Description
camera_border boolean Show camera pane borders
camera_name boolean Show camera name
camera_aspect_ratio float ['0.5625’ or '0.75’]: Aspect ratio of images. .5625 = 16x9, .75 = 4x3
camera_row_limit int ['3’ or '4’ or '5’]: Max number of cameras to show per row

Get Layout

Request

curl -G https://login.eagleeyenetworks.com/g/layout -d "A=[AUTH_KEY]&id=[LAYOUT_ID]"

Returns layout object by Id

HTTP Request

GET https://login.eagleeyenetworks.com/g/layout

Parameter Data Type Description Is Required
id string Layout Id true

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges

Create Layout

Request

curl --cookie "auth_key=[AUTH_KEY]" -X PUT -v -H "Authentication: [API_KEY]:" -H "content-type: application/json" https://login.eagleeyenetworks.com/g/layout -d '{"name": "[NAME]", "json":"{\"panes\":[ {} ] }", "types":[""]}'

Json Response

{
    "id": "80ca9ee0-4f28-11e4-81bf-523445989f37"
}

Creates a new layout

HTTP Request

PUT https://login.eagleeyenetworks.com/g/layout

Parameter Data Type Description Is Required
name string Layout Name true
types array[string] Specifies target(s) for layout. Multiple values are allowed. true
configuration json JSON object that defines the layout configuration
shares array[array] Array of arrays, one per account user for whom sharing is enabled for this layout. Each string contains two fields separated by a comma. The first field is a user id and the second field is the list of permissions for the user. Two special user IDs exist: 'account’ specifies that the layout is shared with all users of the account. The second field contains permissions for users in the account. Example: ['cafedead’, 'RWDS’] = user can view, change, delete or share this layout. ['cafe0001’, 'RW’] = user can view and change this layout. ['account’, 'R’] = All users in the account can view the layout. Permissions for the user issuing the /layout GET are not included in this array.

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges

Update Layout

HTTP Request

POST https://login/eagleeyenetworks.com/g/layout

Parameter Data Type Description Is Required
name string Unique identifier of layout true
id string Layout Name true
types array[string] Specifies target(s) for layout. Multiple values are allowed. true
configuration json JSON object that defines the layout configuration
shares array of array Array of arrays, one per account user for whom sharing is enabled for this layout. Each string contains two fields separated by a comma. The first field is a user id and the second field is the list of permissions for the user. Two special user IDs exist: 'account’ specifies that the layout is shared with all users of the account. The second field contains permissions for users in the account. Example: ['cafedead’, 'RWDS’] = user can view, change, delete or share this layout. ['cafe0001’, 'RW’] = user can view and change this layout. ['account’, 'R’] = All users in the account can view the layout. Permissions for the user issuing the /layout GET are not included in this array.

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges

Delete Layout

Request

curl --cookie "auth_key=[AUTH_KEY]" -X DELETE -v -H "Authentication: [API_KEY]:" -H "content-type: application/json" https://login.eagleeyenetworks.com/g/layout -d "id=[LAYOUT_ID]" -G

HTTP Request

DELETE https://login.eagleeyenetworks.com/g/layout

Parameter Data Type Description
id string Layout Id

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges
404 Layout matching the ID was not found

Get List of Layouts

Request

curl --cookie "auth_key=[AUTH_KEY]" --request GET https://login.eagleeyenetworks.com/g/layout/list

Json Response

[
    [
        "0b58ec7a-61e4-11e3-8f7d-523445989f37",
        "Everything",
        [
            "mobile"
        ],
        "SWRD"
    ],
    [
        "75c03026-719a-11e3-afba-ca8312ea370c",
        "Glenn",
        [
            "mobile"
        ],
        "SWRD"
    ],
    [...],
    [...],
    [...]
]

Returns array of arrays, with each sub-array representing a layout available to the user. Please note that the ListLayout model definition below has property keys, but that’s only for reference purposes since it’s actually just a standard array.

HTTP Request

GET https://login.eagleeyenetworks.com/g/layout/list

Response: Layout Model

Array Index Attribute Data Type Description
0 id string Unique identifier for the Layout
1 name string Name of the layout
2 types array[string] Array of types defined for the layout. This attribute has not yet been implemented.
3 permissions string String of zero or more characters. Each character defines a permission that the current user has for the layout. Permissions include: 'R’ - user can view this layout. 'W’ - user can modify this layout. ’D’ - user can delete this layout. ’S’ - user can share this layout.

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges

Terms of Service

The following API endpoints are to facilitate presenting and accepting the Terms of Service. Eagle Eye Networks has their own terms of services which will be presented through the Get Terms of Service for User. Additionally resellers can add their own Terms of Service through the Get Terms of Service for Account, which will then also be presented with Eagle Eye Network’s terms.

Resellers can assign their own terms at the master account level or give each sub account custom terms at the sub account level.

The basic work process is as follows:

  1. Resellers create their own terms with the Get Terms of Service for Account
  2. Client UI will display terms if not accepted from a Get Terms of Service for User
  3. Client UI will accept the terms from a Accept Terms of Service for User

Get Terms of Service for User

Request

curl -X GET https://28888.eagleeyenetworks.com/g/account/terms?id=00009436 --cookie "auth_key=[AUTH_KEY]"

Response List

[['00009436', 'UNIT_TEST_SUB_ACCOUNT', 'Test_Terms_of_Service2', '2', 1, 0, '20150626191625', 'https://login.eagleeyenetworks.com/static_assets/terms_of_service/00009074/Test_Terms_of_Service2~2~20150626191625.txt', 'active'], ['00009436', 'UNIT_TEST_SUB_ACCOUNT', 'Test_Terms_of_Service', '1', 1, 1, '20150626191617', 'https://login.eagleeyenetworks.com/static_assets/terms_of_service/00009074/Test_Terms_of_Service~1~20150626191617.txt', 'retired'], ['00009436', 'UNIT_TEST_SUB_ACCOUNT', 'Test_Terms_of_Service', '2', 0, 1, '20150626191622', 'https://login.eagleeyenetworks.com/static_assets/terms_of_service/00009074/Test_Terms_of_Service~2~20150626191622.txt', 'active'], ['00009436', 'UNIT_TEST_SUB_ACCOUNT', 'EEN_Terms_of_Service', '1.2', 1, 1, '20150626191610', 'https://login.eagleeyenetworks.com/static_assets/terms_of_service/00000001/EEN_Terms_of_Service~1.2~20150626191610.txt', 'active']]

This is to push important terms of service such as “Terms and Conditions (2015)”. The client software must call GET to see if the user needs to agree to any new terms of service. If the user has a is_compliant of False then the client software should popup a message box containing the terms of service. It is preferred to have this as a single combined message box.

If the user agrees to the terms then a PUT call should be placed containing array all of the notices. A past due user is subject to suspension of services, and may not be allowed to login.

HTTP Request

GET https://login.eagleeyenetworks.com/g/user/terms

Parameter Data Type Description Is Required
id string User Id false

HTTP List Attributes

Parameter Data Type Description
user_id string Unique identifier for validated user
title string Title of the terms of service
url string Url of a file with the text of the terms of service
version string Version string for the title of the terms of service
is_compliant bool If False then the user needs to accept the terms of service

Error Status Codes

HTTP Status Code Data Type
400 Unexpected or non-identifiable arguments are supplied
406 Information supplied could not be verified
402 Account is suspended
460 Account is inactive
409 Account has already been activated
412 User is disabled
200 User has been authorized for access to the realm

Accept Terms of Service for User

This is called to record acceptance of the notice. Account Super Users will not be able to accept for other people.

Request

curl -X PUT https://28888.eagleeyenetworks.com/g/user/terms -d '{"id": "cafe81f5", "urls": ["https://login.eagleeyenetworks.com/static_assets/terms_of_service/00009074/Test_Terms_of_Service2~2~20150626191625.txt", "https://login.eagleeyenetworks.com/static_assets/terms_of_service/00000001/EEN_Terms_of_Service~1.2~20150626191610.txt"]}' -H "content-type: application/json" --cookie "auth_key=[AUTH_KEY]"

Response Json

{'id': 'cafe81f5'}

HTTP Request

PUT https://login.eagleeyenetworks.com/g/user/terms

Parameter Data Type Description Is Required
urls array[string] Array of urls that are accepted true

HTTP Json

Parameter Data Type Description
id string user id

Error Status Codes

Code Data Type
400 Unexpected or non-identifiable arguments are supplied
402 Account is suspended
404 Notice Title was not found
406 Information supplied could not be verified
460 Account is inactive
409 Account has already been activated
412 User is disabled
200 User has been authorized for access to the realm

Create Terms of Service for Account

Master Accounts (Resellers) may require their own terms of service. For that case, this api endpoint is to submit the text of the terms of service.

New terms can be submitted with a PUT command, then a GET command can be done to see the state of the terms. PUT will retire terms of service of the same title and account. Notices can be stored in the sub account or the parent account of the user. Resellers are limited to 5 terms of service titles and each title will only have one active version.

Request

curl -X PUT https://28888.eagleeyenetworks.com/g/account/terms -d '{"is_admin_required": 1, "is_user_required": 1, "title": "Test Terms of Service", "text": "This is a test terms and service from resellers", "version": "1", "id": "00009436"}' -H "content-type: application/json" --cookie "auth_key=[AUTH_KEY]"

Response Json

{'status': 'active', 'is_admin_required': 1, 'is_user_required': 1, 'title': 'Test_Terms_of_Service', 'url': 'https://login.eagleeyenetworks.com/static_assets/terms_of_service/00009074/Test_Terms_of_Service~1~20150626191617.txt', 'timestamp': '20150626191617', 'version': '1', 'user': 'cafebead', 'account_id': '00009074'}

HTTP Request

PUT https://login.eagleeyenetworks.com/g/account/terms

Parameter Data Type Description Is Required Default Limitation
text string Text of the terms to accept true use single LF character for line break
id string Unique id of the Account false requester’s account
title string Title of the terms to accept false “Terms and Conditions” 32 bytes of alpha numeric characters
version string Version of the title, which should be unique false auto incrementing number 32 bytes of alpha numeric characters
is_admin_required bool If admins have to accept false not updating
is_user_required bool If users have to accept false not updating
timestamp string Date the terms goes into affect false now

HTTP JSON Attributes

Parameter Data Type Description
title string Title of the notice
version int Version number for the notice title, a larger version number will retire other versions
is_admin_required bool If admins have to accept
is_user_required bool If users have to accept
timestamp string date of the term of service
url string URL of the file containing the text for the notice
status string Status of the term of service (active, retired)

Error Status Codes

Code Data Type
400 Unexpected or non-identifiable arguments are supplied
402 Account is suspended
404 Terms Title was not found
406 Information supplied could not be verified
460 Account is inactive
409 Account has already been activated
412 User is disabled
200 User has been authorized for access to the realm

Update Terms of Service for Account

Updates an account terms of service as specified by Put Terms of Service for Account. Users are not required to accept terms of the same version again, so if users should be forced to accept again then PUT should be done

Request

curl -X POST https://28888.eagleeyenetworks.com/g/account/terms -d '{"is_admin_required": 0, "is_user_required": 1, "title": "Test Terms of Service", "text": "This is a test terms and service from resellers", "version": "2", "id": "00009436"}' -H "content-type: application/json" --cookie "auth_key=[AUTH_KEY]"

Response Json

{'status': 'active', 'is_admin_required': 0, 'is_user_required': 1, 'title': 'Test_Terms_of_Service', 'url': 'https://login.eagleeyenetworks.com/static_assets/terms_of_service/00009074/Test_Terms_of_Service~2~20150626191622.txt', 'timestamp': '20150626191622', 'version': '1', 'user': 'cafebead', 'account_id': '00009074'}

HTTP Request

POST https://login.eagleeyenetworks.com/g/account/terms

Parameter Data Type Description Is Required Default Limitation
text string Text of the terms to accept false use single LF character for line break
id string Unique id of the Account false requester’s account
title string Title of the terms to accept false “Terms and Conditions” 32 bytes of alpha numeric characters
version string Version of the title, which should be unique false auto incrementing number 32 bytes of alpha numeric characters
is_admin_required bool If admins have to accept false not updating
is_user_required bool If users have to accept false not updating
timestamp string Date the term of service goes into affect false now

HTTP JSON Attributes

Parameter Data Type Description
title string Title of the notice
version int Version number for the notice title, a larger version number will retire other versions
is_admin_required bool If admins have to accept
is_user_required bool If users have to accept
timestamp string date of the term of service
url string URL of the file containing the text for the notice
status string Status of the term of service (active, retired)

Error Status Codes

Code Data Type
400 Unexpected or non-identifiable arguments are supplied
402 Account is suspended
404 Notice Title was not found
406 Information supplied could not be verified
460 Account is inactive
409 Account has already been activated
412 User is disabled
200 User has been authorized for access to the realm

Delete Terms of Service for Account

This will retire a term of service. * Only master accounts can DELETE an account’s terms of service

curl -X DELETE https://28888.eagleeyenetworks.com/g/user/terms?id=cafe81f5 --cookie "auth_key=[AUTH_KEY]"

Response Json

{ 'cafe81f5': { 'EEN_Terms_of_Service': { '1.2': '20150626193818.274'},
                 'Test_Terms_of_Service': { '2': '20150626193626.502'}}}

DELETE https://login.eagleeyenetworks.com/g/account/terms

Parameter Data Type Description Is Required
id string Account id false
title string Title of the terms false

HTTP List Attributes

Parameter Data Type Description
account_id string Unique Id of the account that is requesting this term of service
account_name string Name of the account that is requesting this term of service
title string Title of the term of service
version int Version number for the term title
is_admin_required bool If admins have to accept
is_user_required bool If users have to accept
timestamp string date of the term of service
url string URL of the file containing the text for the term of service
status string This will be retired

Error Status Codes

Code Data Type
400 Unexpected or non-identifiable arguments are supplied
402 Account is suspended
404 Notice Title was not found
406 Information supplied could not be verified
460 Account is inactive
409 Account has already been activated
412 User is disabled
200 User has been authorized for access to the realm

Get Terms of Service for Account

Request

curl -X GET https://28888.eagleeyenetworks.com/g/account/terms?id=00009436 --cookie "auth_key=[AUTH_KEY]"

Response List

[['00009436', 'UNIT_TEST_SUB_ACCOUNT', 'Test_Terms_of_Service2', '2', 1, 0, '20150626191625', 'https://login.eagleeyenetworks.com/static_assets/terms_of_service/00009074/Test_Terms_of_Service2~2~20150626191625.txt', 'active'], ['00009436', 'UNIT_TEST_SUB_ACCOUNT', 'Test_Terms_of_Service', '1', 1, 1, '20150626191617', 'https://login.eagleeyenetworks.com/static_assets/terms_of_service/00009074/Test_Terms_of_Service~1~20150626191617.txt', 'retired'], ['00009436', 'UNIT_TEST_SUB_ACCOUNT', 'Test_Terms_of_Service', '2', 0, 1, '20150626191622', 'https://login.eagleeyenetworks.com/static_assets/terms_of_service/00009074/Test_Terms_of_Service~2~20150626191622.txt', 'active'], ['00009436', 'UNIT_TEST_SUB_ACCOUNT', 'EEN_Terms_of_Service', '1.2', 1, 1, '20150626191610', 'https://login.eagleeyenetworks.com/static_assets/terms_of_service/00000001/EEN_Terms_of_Service~1.2~20150626191610.txt', 'active']]

HTTP Request

GET https://login.eagleeyenetworks.com/g/account/terms

Parameter Data Type Description Is Required
id string Account id false

HTTP List Attributes

Parameter Data Type Description
account_id string Unique Id of the account that is requesting this notice
account_name string Name of the account that is requesting this notice
title string Title of the notice
version int Version number for the notice title, a larger version number will retire other versions
is_admin_required bool If admins have to accept
is_user_required bool If users have to accept
timestamp string date of the term of service
url string URL of the file containing the text for the notice
status string Status of the term of service (active, retired)

Error Status Codes

HTTP Status Code Data Type
400 Unexpected or non-identifiable arguments are supplied
406 Information supplied could not be verified
402 Account is suspended
460 Account is inactive
409 Account has already been activated
412 User is disabled
200 User has been authorized for access to the realm

Action

Overview

This service defines several macro actions that can be attached to devices. These are convenience functions. The same functionality provided herein can also be accomplished via individual setting calls. Most actions can be scheduled to occur now or at some point in the future.

Given the macro nature and the number of devices and operations that may occur, so long as the arguments are correct, the services will return success status code. The application should monitor the vent stream to determine success of failure of the action on a device by device basis.

Recording On

Request TODO

Used to turn on recording for 1 camera, all cameras, or all cameras in a specific layout. The result of this to the affected cameras will be that all ‘operating_hours’ schedules are removed, 'camera_on’ is set to 1 (on) and 'video_capture_mode’ is set to 'always’.

HTTP Request

POST https://login.eagleeyenetworks.com/g/action/recordnow

Parameter Data Type Description
device_id string ID of the camera to record. If this parameter and the 'layout_id’ parameter are omitted, all cameras with write access available to the requesting user will be used.
layout_id string ID of the layout whose cameras will be set to record. All cameras in the layout will be affected. If this parameter and the 'device_id’ parameter are omitted, all cameras with write access available to the requesting user will be used.
recording_key string A key used to tag this recording. Can be used to retrieve this recording info later using the GET 'recording’ service.

Error Status Codes

HTTP Status Code Data Type
202 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges

Recording Off

Request TODO

Used to turn off recording for 1 camera, all cameras, or all cameras in a specific layout. The result of this to the affected cameras will be that all 'operating_hours’ schedules are removed, 'camera_on’ is set to 0 (off) and 'video_capture_mode’ is set back to 'event’ (the default).

HTTP Request

POST https://login.eagleeyenetworks.com/g/action/recordoff

Parameter Data Type Description
device_id string ID of the camera to turn off recording for. If this parameter and the 'layout_id’ parameter are omitted, all cameras with write access available to the requesting user will be used.
layout_id string ID of the layout whose cameras will have recording turned off. All cameras in the layout will be affected. If this parameter and the 'device_id’ parameter are omitted, all cameras with write access available to the requesting user will be used.

Error Status Codes

HTTP Status Code Data Type
202 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges

Turn All Cameras On

Request

curl --cookie "auth_key=[AUTH_KEY]" --request POST https://login.eagleeyenetworks.com/g/action/allon

Used to turn on all cameras in the caller user’s account. Caller must be an account superuser

HTTP Request

POST https://login.eagleeyenetworks.com/g/action/allon

Error Status Codes

HTTP Status Code Data Type
202 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges

Turn All Cameras Off

Request

curl --cookie "auth_key=[AUTH_KEY]" --request POST https://login.eagleeyenetworks.com/g/action/alloff

Used to turn off all cameras in the caller user’s account. Caller must be an account superuser

HTTP Request

POST https://login.eagleeyenetworks.com/g/action/alloff

Error Status Codes

HTTP Status Code Data Type
202 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges

Feedback

Overview

This service allows users to send feedback to support.

Send Feedback

Request

curl --cookie "auth_key=[AUTH_KEY]" --request POST https://login.eagleeyenetworks.com/g/feedback --data "subject=[SUBJECT]&message=[MESSAGE]"

Sends feedback to support

HTTP Request

POST https://login.eagleeyenetworks.com/g/feedback

Parameter Data Type Description
subject string Subject of the feedback
message string Feedback message

Error Status Codes

HTTP Status Code Data Type
202 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges

Metric

Overview

This service defines metrics that can be queried from the system.

Camera Bandwidth

Request

curl -G https://login.eagleeyenetworks.com/g/metric/camerabandwidth -d "A=[AUTH_KEY]&id=[CAMERA_ID]"

Used to query the bandwidth usage for a particular camera device.

HTTP Request

GET https://login.eagleeyenetworks.com/g/metric/camerabandwidth

Parameter Data Type Description Is Required
id string Bridge Id true
start_timestamp string Start timestamp of query, in EEN format: YYYYMMDDHHMMSS.NNN. Defaults to 7 days ago.
end_timestamp string End timestamp of query, in EEN format: YYYYMMDDHHMMSS.NNN. Defaults to now.
group_by string, enum Hour or Day, indicating how the results should be grouped.

enum: day, hour, minute
motion_interval int Motion Interval used for Motion Activity metric, in milliseconds. Defaults to 15000.
metric string, enum String delimited list used to filter which metrics gets returned. Setting this parameter to ‘core,motion’ will return data only for core and motion.

enum: core, packets, motion

Json Response

{
    "core": [
        [
            "20141002190000.000",
            0.0,
            0.0,
            215910545.0,
            76733036.0,
            32049659.0,
            52716510.0
        ],
        [
            "20141002200000.000",
            0.0,
            0.0,
            252051927.0,
            164214711.0,
            36128066.0,
            223484133.0
        ],
        [...],
        [...],
        [...],
        [
            "20141009190000.000",
            0.0,
            0.0,
            41425890.0,
            10373660.0,
            5029677.0,
            78599812.0
        ]
    ],
    "packets": [
        [
            "20141002190000.000",
            0.00183
        ],
        [
            "20141002200000.000",
            0.0018439999999999999
        ],
        [...],
        [...],
        [...],
        [
            "20141009190000.000",
            0.0
        ]
    ],
    "motion": []
}

Response Json Attributes

Parameter Data Type Description
core array[CameraCore] Array of core metrics
packets array[CameraPackets] Array of packet metrics
motion array[CameraMotion] Array of motion metrics

CameraCore Json Array Elements

Index Data Type Description
0 string EEN Timestamp: YYYYMMDDHHMMSS.NNN
1 float Average Kilobytes on Disk
2 float Average Days on Disk
3 float Bytes Stored
4 float Bytes Shaped
5 float Bytes Streamed
6 float Bytes Freed

CameraPackets Json Array Elements

Index Data Type Description
0 string EEN Timestamp: YYYYMMDDHHMMSS.NNN
1 float Packet loss percentage (decimal)

CameraMotion Json Array Elements

Index Data Type Description
0 string EEN Timestamp: YYYYMMDDHHMMSS.NNN
1 int motion activity value

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges
404 Metrics not found

Bridge Bandwidth

Request

curl -G https://login.eagleeyenetworks.com/g/metric/bridgebandwidth -d "A=[AUTH_KEY]&id=[BRIDGE_ID]"

Used to query the bandwidth usage for a particular bridge device.

HTTP Request

GET https://login.eagleeyenetworks.com/g/metric/bridgebandwidth

Parameter Data Type Description Is Required
id string Bridge Id true
start_timestamp string Start timestamp of query, in EEN format: YYYYMMDDHHMMSS.NNN. Defaults to 7 days ago.
end_timestamp string End timestamp of query, in EEN format: YYYYMMDDHHMMSS.NNN. Defaults to now.
group_by string, enum Hour or Day, indicating how the results should be grouped.

enum: day, hour, minute

Json Response

{
    "core": [
        [
            "20141002170000.000",
            711610368.0,
            673860608.0,
            21533380.0,
            10299.0,
            10064282.0,
            9903.0
        ],
        [
            "20141002180000.000",
            711610368.0,
            673802922.66666698,
            139693604.0,
            16579176.0,
            30849223.0,
            70446106.0
        ],
        [...],
        [...],
        [...],
        [
            "20141009170000.000",
            711610368.0,
            674052608.0,
            20663486.0,
            8637204.0,
            18879693.0,
            19383808.0
        ]
    ],
    "bandwidth": [
        [
            "20141002180000.000",
            253117.37089200001
        ],
        [
            "20141002220000.000",
            240255.52353499999
        ],
        [...],
        [...],
        [...],
        [
            "20141009150000.000",
            232692.09302299999
        ]
    ],
    "storage": [
        [
            "20141002170000.000",
            21523477
        ],
        [
            "20141002180000.000",
            69247498
        ],
        [...],
        [...],
        [...],
        [
            "20141009170000.000",
            1279678
        ]
    ]
}

Response Json Attributes

Parameter Data Type Description
core array[BridgeCore] Array of core metrics
bandwith array[BridgeBandwidth] Array of bandwidth metrics
storage array[BridgeStorage] Array of storage metrics

BridgeCore Json Array Elements

Index Data Type Description
0 string EEN Timestamp: YYYYMMDDHHMMSS.NNN
1 float Average Kilobytes on Disk
2 float Average Days on Disk
3 float Bytes Stored
4 float Bytes Shaped
5 float Bytes Streamed
6 float Bytes Freed

BridgeBandwidth Json Array Elements

Index Data Type Description
0 string EEN Timestamp: YYYYMMDDHHMMSS.NNN
1 float Bytes per second

BandwidthStorage Json Array Elements

Index Data Type Description
0 string EEN Timestamp: YYYYMMDDHHMMSS.NNN
1 float Bytes Diff

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges
404 Metrics not found

Png Span

Overview

This service offers native PNG span rendering to support metric visualization. For spans, the image is filled with the foreground color where the specified span is active, and with the background where it is inactive. At least one pixel will be filled for a span, independent of scale, though the span may overlap others. For etags, one pixel is filled for each active event, but as with spans the pixel may overlap others.

Response Headers

content-location: resource actually rendered. absolute start/end ts and either table/etag depending on whether an index was used

Discussion

The pngspan is a very efficient mechanism for visualizing where metrics and spans are active. Scale the image vertically as needed. PNG are extremely compact - a day of spans will be a few hundred bytes.

Tile the PNGs for fast, infinite scrolling. Render a width/timespan that represents a rational chunk of the current screen - say 4 hours in a day view. Fill the screen with tiles, fetch offscreen at the same size in preparation to scroll. Change origin of each entity to accomplish fast smooth scrolling. Fetch successive offscreen buffers as they come on screen.

Hit detection (for rollover) can be done in a browser by rendering opaque colors and reading pixels values from a one pixel high offscreen image. If an active pixel is detected, fetch the window of events around the timestamp estimate (since the pixel resolution is usually much less than the ms resolution needed for a timestamp), and use the response to determine what metric/span to display (ie the closest one…).

PNG Types

Get Png Span

Request

curl -G https://login.eagleeyenetworks.com/pngspan/span.png -d "start_timestamp=[START_TIMESTAMP]&end_timestamp=[END_TIMESTAMP]&width=[WIDTH]&id=[CAMERA_ID]&foreground_color=[FOREGROUND_COLOR]&background_color=[BACKGROUND_COLOR]&table=[TABLE]&A=[AUTH_KEY]"

PNG images can be retrieved for supporting metric visualization. PNG types include

HTTP Request

GET https://login.eagleeyenetworks.com/pngspan/{png_type}.png

Parameter Data Type Description Is Required
start_timestamp string Start Timestamp in EEN format: YYYYMMDDHHMMSS.NNN true
end_timestamp string End Timestamp in EEN format: YYYYMMDDHHMMSS.NNN true
width int Width in pixels of resulting PNG. Must be an integer greater than 0. true
id string Camera Id true
foreground_color string Color of foreground (active). If both fg and bg have 0 for alpha, assumed fully opaque (0xff). 32bit ARGB color. true
background_color string Color of background (inactive). 32bit ARGB color. true
table string, enum If provided, specifies name of table to be rendered. Required for type ‘span’ and 'event’.

enum: stream, onoff, video, register
etag string Indentifies etag to be rendered, using the 4 character string identifier ('4CC’). Will utilize matching event tables where possible. Ignored for type 'span’ and 'event’.
flval string Identified value of the filter field from the starting etag. Only applicable for type 'span’.
flname string Name of field within span start etag to match to flval. Interesting fields are roiid in roim table and videoid for video. Only applicable for type 'span’.
flflags string Limits span rendering to spans with the flag asserted. ALERTS is asserted for roim and motion spans when an alert is active.
HTTP Status Code Data Type
200 Request succeeded
401 Unauthorized due to invalid session
404 Not found if camera, etag or table cannot be found
408 Required arguments are missing or invalid
500 Problem occurred during data processing or rendering

Recording

Overview

This service is used to retrieve and update recording info for recordings that were started/stopped using the “action/recordnow” and “action/recordoff” services.

Get Recording Object

Request TODO

Json Response TODO

Returns recording object by recording_key.

HTTP Request

GET https://login.eagleeyenetworks.com/g/recording

Parameter Data Type Description
recording_key string Recording Key

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges

Update Recording Object

Request TODO

Json Response TODO

Update a Recording

HTTP Request

POST https://login.eagleeyenetworks.com/g/recording

Parameter Data Type Description
recording_key string Unique identifier (within an account) of a recording
meta object Meta data. This is meant to be a generic object that can store any data that is needed, so the properties are not predefined.

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges

Search

Overview

This service allows for search across various types of data. Currenlty only supports recordings and annotations, but support for other types of data is coming soon.

Search Recordings

Request TODO

Json Response TODO

Returns array of recording objects that match a search value.

HTTP Request

GET https://login.eagleeyenetworks.com/g/search/recordings

Parameter Data Type Description
value string Value to search for

Response Json Attributes

Parameter Data Type Description
_key string Unique identifier (within the user’s account) of the recording
current_recording_timestamp string Timestamp of when the current recording (if any) was started
recording_%s_start RecordingInfo Object of info about the recording start event, where ’%s’ is the timestamp it started. Could be N number of these.
recording_%s_stop RecordingInfo Object of info about the recording stop event, where ’%s’ is the timestamp it started. Must have a matching ‘recording_%s_start’ event. Could be N number of these.
recording_%s_meta object Object of info about the recording, where ’%s’ is the timestamp it started. Must have a matching 'recording_%s_start’ event.

RecordingInfo Json Attributes

Parameter Data Type Description
timestamp string Timestamp the recording was started, in EEN format.
layout_id boolean Id of a layout the recording was started for
camera_ids array[string] Array of camera ids who had recording started for
layout_name string Name of layout at the time the recording started
user_id string Id of the user who started/stopped the recording

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges

Search Annotations

Request TODO

Json Response TODO

Returns array of annotation objects that match a search value.

HTTP Request

GET https://login.eagleeyenetworks.com/g/search/recordings

Parameter Data Type Description Is Required
value string Value to search for true
start_timestamp string Start timestamp (in EEN format) to use to limit search results true
end_timestamp string End timestamp (in EEN format) to use to limit search results. Defaults to now.

Response

array[object]

Error Status Codes

HTTP Status Code Data Type
200 Request succeeded
400 Unexpected or non-identifiable arguments are supplied
401 Unauthorized due to invalid session cookie
403 Forbidden due to the user missing the necessary privileges

Errors

Error Code Meaning
200 The request was fulfilled successfully
202 The request has been accepted for processing, but the processing has not been completed
400 The request had bad syntax or was inherently impossible to be satisfied
401 Supplied credentials are not valid
402 Account is suspended
403 Forbidden due to the user missing the necessary privileges
406 Realm is invalid due to not being a root realm
409 Email address has already been registered for the specified realm
412 User is disabled
460 Account is inactive
461 Account is pending
462 User is pending

FAQ

Who can use the Eagle Eye APIs?
The Eagle Eye Video API are publicly open for anyone to use. Users will need a valid API key to successfully make API calls.

How do I get my API key?
You can get an API key by filling out the form here.

I found an error with Eagle Eye Video API, where should I report it?
For API specific questions, issues, or feature requests, please submit a request here

How do you charge for the Eagle Eye Video API use?
The Eagle Eye Video API does not require any additional fees for use. The only fees are the per camera fees for the use of the Eagle Eye system.

What can I do with the Eagle Eye API?
The Eagle Eye Video API provides a robust set of storage, analytics, indexing, and interfaces for quickly building or integrating applications with both live and recorded video; the applications can range from very simple or highly complex. See our HowTos and Examples page here.

How To’s and Example Code

Making API Calls With Curl

In this section, we will walk you through the process of making API requests using the ‘curl’ command line tool. The Eagle Eye APIs are platform agnostic and we use them to create the web, Android, and iOS Eagle Eye clients. Curl is a tool for transferring data to and from a server, using a wide range of supported protocols, including HTTP/HTTPS, which is what we are interested in. Curl can be installed by going to this site. http://curl.haxx.se/.

With curl installed, the next step is to log in and have a valid session, so that we can freely use any of the APIs. Logging in, is a two step process consisting of authentication and authorization. The authentication API takes in 2 parameters. Our curl common will look like this. The [USERNAME] and [PASSWORD] need to be valid for the API request to return successfully.

curl --request POST https://login.eagleeyenetworks.com/g/aaa/authenticate --data 'username=[USERNAME]&password=[PASSWORD]'

The ‘–request’ flag specifies the type of request and can be set to GET, POST, PUT, and DELETE. The ‘data’ flag species the parameters of the API query. Upon running this command with valid credentials, we receive a Json formatted response, containing a key/value pair for ‘token’, which will look something like this.

{ “token”: “YrZF/8jf7W0rKcqNTugqidq…………4dZWeNOcNsuenTXc9fQVtvp2vI75g==” }

This token is a required parameter for making the Authorize API request. Copy the value of the token in order to have it on hand when creating the Authorize API request. Now we make the authorization API request using this curl command.

curl -D - --request POST https://login.eagleeyenetworks.com/g/aaa/authorize --data-urlencode token=[TOKEN]

The output are the headers of the API request followed by the response body. The ‘-D’ flag is used to write the protocol headers. Here is the description from the man pages.

-D, –dump-header <file> Write the protocol headers to the specified file. This option is handy to use when you want to store the headers that a HTTP site sends to you. Cookies from the headers could then be read in a second curl invocation by using the -b, –cookie option! The -c, –cookie-jar option is however a better way to store cookies.

Note that the ‘-‘ after the ‘-D’ indicates that the output “file” is stdout. One of the header elements will be “Set-Cookie: auth_key=[AUTH_KEY]“. Copy ‘auth_key=[AUTH_KEY]‘ into the clipboard as this cookie will need to be set for all other API requests. The curl request for getting a list of devices will look as such.

curl --cookie "auth_key=[AUTH_KEY]" --request GET https://login.eagleeyenetworks.com/g/list/devices

The ‘auth_key’ cookie will need to be set for any other Eagle Eye API that requires a valid session.

Constructing Layouts

Get /layout/list

[
    [
        "fc7fa3a4-66ea-11e3-8ca8-523445989f37",
        "Default",
        [
            "iphone"
        ],
        "SWRD"
    ],
    [
        "14fbd682-66eb-11e3-8ca8-523445989f37",
        "Ekta 2",
        [
            "iphone"
        ],
        "SWRD"
    ],
    [
        "23535930-66eb-11e3-977b-ca8312ea370c",
        "Ekta 3",
        [
            "desktop"
        ],
        "SWRD"
    ]
]

When a user logs onto the Eagle Eye system, they are greeted with a grid of cameras, with each cell representing a camera pane. These panes can be of varying size so that the user can customize the layout to their liking. In this tutorial, we will demonstrate how to use the APIs to build these layouts so they are consistent on all platforms.

Upon being logged in, we make a request to the GET /layout/list API. This returns an array of Layout objects. Do note that this is not the same model as what is returned by the GET /layout API request. The one returned by the /layout/list API is an abridged version with only the most important attributes. The response of the request will look like this.

Get /layout/list

We take the layout id attribute for each layout of interest and pass it to the Get /layout API request. This will contain the information we need to construct the layout.

Get /layout

Get /layout

{
    "id": "811dbe48-66eb-11e3-8ca8-523445989f37",
    "shares": [
        [
            "ca0c35cb",
            "SWRD"
        ]
    ],
    "name": "mob dev 1",
    "permissions": "SWRD",
    "current_recording_key": null,
    "types": [
        "desktop"
    ],
    "configuration": {
        "settings": {
            "camera_row_limit": 3,
            "automatic_rotation": false,
            "camera_name": false,
            "camera_border": "false",
            "camera_aspect_ratio": "0.75"
        },
        "panes": [
            {
                "type": "preview",
                "pane_id": 0,
                "name": "Conference Room",
                "cameras": [
                    "100f6136"
                ],
                "size": 2
            },
            {
                "type": "preview",
                "pane_id": 1,
                "name": "NW Parking",
                "cameras": [
                    "10003254"
                ],
                "size": 2
            }
        ]
    }
}

We get a wealth of good information, but the information specific to setting up the pane layout is in the ‘configuration’ json. Within that json, there is an attribute called ‘panes’ which is an array of individual pane objects. Each pane specifies the camera_id and the size of the pane. The size represents the width and height in number of cells. A size of 2 means that the pane is 2 cells in width and height, so it occupies a total of 4 cells. A size of 3 would occupy 9 cells.

The other important factor to know is the size of grid holding the panes, specifically the number of columns. For the Eagle Eye web client, a browser can be resized to be a narrow strip or the full width of the screen. The layout will dynamically adjust the number of columns based on the width of the window. Mobile devices have fixed screen sizes, so for the iOS and Android smartphone clients, we set the number of columns to three.

Now that we have the order of the panes, the size of each pane, and the size of the grid, we can construct our layout. This proved to be of varying difficulty depending on the platform. The web client uses a robust packing library, Packery, which is based on a bin packing algorithm. http://metafizzy.co/blog/packery-released/. This library minimizes empty space while preserving the order as best as possible. Using Packery reduced the development time for this feature significantly.

At the time of this writing, Android does not have a robust library for packing the panes so the algorithm to do so was written from scratch. The goal was to mimic the Packery library as best as possible. The Android algorithm works as such:

  1. Remove the next image from the ‘panes’ array and place it in the ‘panes_for_analysis’ list.
  2. Analyze the panes in ‘panes_for_analysis’. If there is a fully packed block, remove those panes and add them to the layout
  3. If the ‘panes’ array is not empty, GOTO 1, else GOTO 4
  4. Add the remaining panes from ‘panes_for_analysis’ to the layout.

This is the algorithm at a high level, though the specifics can get a little more complex, such as determining whether a fully packed block exists. The state of a fully packed block is also dependent on the number of columns for the grid.

The ease of constructing layouts is highly dependent on the robustness of the 3rd party library. In the case that one does not exist, we fall back to our home grown packing algorithm.

Playing Live Video

Video playback functionality can be accessed through the ‘/asset/play/video.{video_format}’ API. We will show you how to use this API to play live video, though the same API can also be used to play historic video.

Below is the Javascript code that creates the URL for playing live video footage with a HTML flash video player. You can run the javascript code on this site to generate the URL string. http://writecodeonline.com/javascript/.

The caller of the API need to supply 2 parameters. which are [DEVICE_ID] and [AUTH_KEY]. The [DEVICE_ID] represents the id of the camera of interest. The [AUTH_KEY] is used for authentication and can be found in the response header of the /aaa/authorization API.

eagleEyeLiveVideoApiUrl = "https://login.eagleeyenetworks.com/asset/play/video.flv" + "?id=[DEVICE_ID]" + "&start_timestamp=stream_"+(new Date().getTime()) + "&end_timestamp=+300000" + "&A=[AUTH_KEY]";

htmlFlashVideoPlayerUrl = "https://login.eagleeyenetworks.com/strobe/embed.html?src="+encodeURIComponent(eagleEyeLiveVideoApiUrl)+"&autoPlay=true&bufferingOverlay=false&streamType=live&bufferTime=1&initialBufferTime=1&expandedBufferTime=5&liveBufferTime=2&liveDynamicStreamingBufferTime=4&minContinuousPlaybackTime=5";

document.write(htmlFlashVideoPlayerUrl);

Notice that we have 2 variables; ‘eagleEyeLiveVideoApiUrl’ and ‘htmlFlashVideoPlayerUrl’. The ‘htmlFlashVideoPlayerUrl’ variable contains the video player being used to play the Flash Player. Users are free to use any video player of this liking, and the one referenced in the code is just an example video player we are using. The output of this JS code is a URL that looks like this. Use this to embed live video into your application.

https://login.eagleeyenetworks.com/strobe/embed.html?autoPlay=true&src=https%3A%2F%2Flogin.eagleeyenetworks.com%2Fasset%2Fplay%2Fvideo.flv%3Fc%3D[DEVICE_ID]%3Bt%3Dstream_1401291315740%3Be%3D%2B300000%3BA%3D[AUTH_KEY]&bufferingOverlay=false&streamType=live&bufferTime=1&initialBufferTime=1&expandedBufferTime=5&liveBufferTime=2&liveDynamicStreamingBufferTime=4&minContinuousPlaybackTime=5

Long Polling

Json Request for Post /poll

{
     "cameras": {
         "100c30ea": {
             "resource": [
                 "event",
                 "pre",
                 "thumb",
                 "status"
             ],
             "event": [
                 "ECON",
                 "ECOF",
                 "AELI",
                 "AELO",
                 "EMES",
                 "EMEE",
                 "CECF",
                 "CSAT",
                 "CSDT",
                 "CONN",
                 "COFF",
                 "ESES",
                 "ESEE"
             ]
         },
         "100f6136": {
             "resource": [
                 "event",
                 "pre",
                 "thumb",
                 "status"
             ],
             "event": [
                 "ECON",
                 "ECOF",
                 "AELI",
                 "AELO",
             ]
         },
         "1009c1ab": {
             "resource": [
                 "event",
                 "pre",
                 "thumb",
                 "status"
             ],
             "event": [
                 "EMES",
                 "EMEE",
                 "CECF",
                 "CSAT",
                 "CSDT",
                 "CONN",
                 "COFF",
                 "ESES",
                 "ESEE"
             ]
         }
}

Upon entering the Eagle Eye system, the user is presented with a grid of cameras. These cameras are retrieving images in real time through a poll stream. In this tutorial, we will walk you through the steps to set up the poll stream for long polling using the /poll API.

Long polling is used in the mobile clients. The process is to first register to the poll stream using the POST /poll API followed by constant API requests for GET /poll.

The POST /poll API is used to initialize the poll stream and to register the events we want to listen for. For the mobile clients, we are listening to resource type ‘pre’ and ‘status’, which are the preview images and status bits. Since the data we are sending to the server is a json, the content-type of this request will be application/json. Here is an example of what the the data may look like.

Once the POST /poll request has been made successfully, a token is returned to the user. This token can be used to successfully make all subsequent GET /poll requests. If the token is not desired, the same requests can be made if you have the ‘ee-poll-ses’ cookie from the POST /poll request.

The GET /poll request should be called frequently so that new data can arrive as soon as possible. The response may be empty or it may look something like this.

Response for Get /poll


{
    "cameras": {
        "10003254": {
            "event": {
                "PRFR": {
                    "cameraid": "10003254",
                    "timestamp": "20140528224954.312",
                    "file_offset": 17804500,
                    "frame_size": 6152,
                    "previewid": 1401314400
                }
            }
        },
        "100a9541": {
            "event": {
                "PRFR": {
                    "cameraid": "100a9541",
                    "timestamp": "20140528224955.507",
                    "file_offset": 12004385,
                    "frame_size": 3706,
                    "previewid": 1401314400
                }
            },
            "pre": "20140528224955.507"
        }
    }
}

Only attributes with updated information will be returned in the response payload. For the mobile apps, we monitor the ‘pre’ attribute for new timestamps, and when a new timestamp does come in, we make the appropriate API call to retrieve the camera image.

The power of this API lies in the ability of being able to control what events and resource types to listen to. This allows updates to the camera to be known in real time.

Definition of Terms

Eagle Eye Video Bank (EEVB)
The service that Eagle Eye provides that safely, securely, and easily stores video from surveillance and other cameras, allows access via the world wide web, and provides a comprehensive control and management platform for multi camera surveillance.

Eagle Eye Video Bank Services (EEVBS)
This is the exposed WWW RESTful services that are used internally as well as externally for the interface of Cameras, User Interfaces, Mobile Applications, and Image Analysis applications. This is described in this document.

Camera
A camera is a source of video data streams that are delivered to the Eagle Eye Video Bank. Cameras produce streams of Assets over periods of time. These Assets are stored in the EEVB.

CameraID
A unique ID which is a 32 bit hex number. This unique id is used to identify the camera and all of its assets. This id is not the hardware id of the physical camera. It is the logical id of the data stream that has been or is being recorded from a conceptual camera location. If a camera is replaced it can therefore be connected to the same CameraID so the Asset streams can be continuous.

Camera Name
This is a non-unique name that the Admin attaches to a Camera ID for easy reference in identifying the Assets generated by the Camera.

Physical Camera
The actual physical Camera – different than the “logical Camera” which is referred to as the “Camera”.

Device
This is either a Physical Camera or a Bridge.

DeviceID
This is either a CameraID or the equivalent ID for a Bridge. In the case of the Bridge there is no video stream associated with it.

Connect ID
This is 16 digit mixed numeric and alpha string broken into 4 sets of 4 digits. Cameras and Bridges (Devices) have a Connect ID printed on a sticker attached to them and on the inside of the cardboard box (not the outside). If the Device is preconfigured it will automatically attach to the User’s Account. However, if the Device is not pre-configured the Connect ID is entered by the Admin User to attach the Device to his Account. This will typically create one or more Cameras that correspond to the physical cameras and attach them to an Account. Connect ID is always displayed in UPPER CASE only. On entry it is case insensitive. There are no “0”s (zero’s) or “O”s (letter Os) in the Connect ID to eliminate any possible confusion.

Hardware ID
This is the unique ID of the hardware of the Device. This ID varies based on the type of camera and other parameters. It is basically a string of up to 128 characters. A Hardware ID is mapped to a CameraID by the EEVB when the Assets are stored. When physical cameras are attached to a Bridge we use the ONVIF GUID as the Hardware ID.

Account
An Account is the billing entity and the master control entity in the EEVB. All Cameras, Assets, Users, and other items are associated with an Account. Accounts are identified by an Account Number. An Account has Users which are identified by email addresses (which is also their User Login).

Sub-Account
A sub Account is an Account that is under another Account (called the Master Account) A Sub-Account is primarily a billing relationship and for most intents and purposes appears as a complete separate account. There is only 1 level of Sub-Accounts. An Admin of a Master Account can get Admin Access to a Sub-Account via a method still TBD. A Sub-Account has an indicator with regards to billing. A Sub-Account can either be billed via the Master Account or can be billed separately. If Billed separately the Sub-Account operates like any other account. If not billed separately then billing for a Master Account will show all the items of any Sub-Account broken out by Sub-Account, and the Sub-Account will have NO billing of any kind (no permissions, no bill display, no credit card entry – nothing). There must be Eagle Eye admin functionality to change the billing indicator, change Sub-Accounts to Accounts, and move Sub-Accounts to other Master Accounts. Basically Sub-Accounts are used by Resellers; We can keep track of which Accounts are associated with which Reseller, Resellers can get admin access, and we can either bill to the Reseller or bill the customer directly. Sub-Accounts are also used by large companies who want separate billing by division.

Account Number
A 64 bit decimal number that uniquely identifies an Account. This is a numeric number that is assigned by the EEVB when a new Account is created. The Admin User is made aware of his Account Number, but does not need to know it for logging in. He may need it when calling in for billing questions. This Account Number is used to tie into the Eagle Eye accounting systems. All billing is based on an Account.

Account Level
This is a numeric code that identifies the type of Account. Currently we have 4 Account Levels; 1=Eval, 2=Basic, 3=Premium, 4=Enterprise. Different features are available on each of these Account Levels. Different Billing is performed on each of these Account Levels (per Camera costs are different). Each of these Account Levels has a different Default Retention Policy. There will likely be additional Account Levels in the future.

User
Every Account has Users. A User corresponds to a single person or a single station that requires access to the Eagle Eye Video Bank. Users can have different permissions and access. Access control may limit cameras that are visible or actions that can be taken on cameras. Can Users belong to multiple Accounts??

UserID
A UserID is a 32 bit hex number that uniquely identifies a User.. This UserID is assigned by the EEVB when the User is created and is attached to a User.

**User Login
A User’s Login is his email address. This uniquely identifies the user and provides for password recovery. EEVB only supports only email based User Logins. Each User is associated with one and only one Account. Each User will have only one UserID assigned by the system. Can Users belong to multiple Accounts??

Admin User
An Account must have at least one Admin User. The last Admin User cannot be deleted. An Account may have multiple Admin Users. The Admin User can add and delete other users, can change permissions, add and delete Cameras, and view all Assets. The Admin Users will be notified if there are any billing issues and can view the billing history. Admin Users can change billing and purchase additional services.

Camera Tags
Cameras are labeled using Camera Tags for basic configuration management. Any Camera can have any number of Camera Tags. Tags are Global to the account.

Layout
A collection of cameras, the position and size on the screen, the setting associated with the display of the cameras on the screen stored and named. Layouts are used to display cameras on monitor screens and to assist with research work. Layouts are created by Users and named by them. Layouts can be either User specific or global in nature. Account Layouts are visible to all Users of an account. Each Camera Group has an associated implied Layout with it. Layouts have permissions for each User.

Activation
Process when a new camera or bridge comes online and the User acknowledges it, names it, and brings into his system. Billing starts at the Activation time. Any terms and conditions might have to be agreed at activation time as well.

Camera TagID
Token assigned by EEVB to identify a Camera Tag

Assets
Assets are the items stored in the EEVB which have been captured or created by Cameras and Analysis Systems. All Assets are associated with a Camera which in turn is associated to an Account. Normally Assets are previews and video.

Asset Class
There are Asset Classes: 1) Video, 2) Preview, 3) Meta Data. These are produced by the Cameras. The MetaData can also be produced by Analysis Systems.

Saved Assets
Normally Assets are rotated in and rotated out. For example the EEVB might keep the last 14 days of video Assets from a Camera. Saved Assets are those Assets and associated data that a User has indicated need to be saved for a longer period of time. These Assets are copied from the normal rotation (Retention period) so that they are not deleted.

Video Assets
Video assets are recorded streams of video and include audio. Shared Assets Shared Assets are Assets that a User has indicated should be shared to the public, other Users, or other potential locations. These Assets are a subset of Saved Assets.

Events
An Event is a span of time that is indicated as “interesting”. Events are a meta data that adds value to Assets. Cameras generate Events based on detection - motion detection, audio detection etc. Cameras may or may not provide Preview Assets or Video Assets when Events are generated. Many events trigger recording or saving of Assets. Events can also be User generated (A recording is scheduled, Video is streamed, tagged or saved). Events may be generated by Analysis systems (identification of license plates). Events have Meta Data which indicate additional information about them (why they were recorded, specific details for each detection type etc.). Events all start at a specific time and for a specific cameras. Events normally have length, but the length can also be zero. Data can be attached to an event when its created or later (Users can add comments to an event, an Analysis System can associate names with faces.) Events are a primary element of the Eagle Eye UI.

Incomplete Event
Events have a beginning and an end. Events may be received or obtained before they are completed. In this case they are considered an Incomplete Event. This is most common when using the “polling interface” and receiving events in real time. In the Polling interface if an Incomplete Event is received, then when the event completes, it will be received again.

Span
A span is a duration of time between two events that compliment each other.

Key Frame
Image that is the representative image of an Event. Generally selected from the middle of a motion segment.

Analysis Systems
Analysis Systems use the EEVBS to analyze existing or incoming Assets and attach meta data to the Assets in the form of Meta Data Assets. The Meta Data can identify people, places, and things in the Asset Streams. This Meta Data can then be searched, organized, analyzed, and alerted upon.

Alerts/Notifications
Alerts or Notifications are generated from Events when the User has created criteria to create them. Alerts may be given in any number of methods (on screen, email, text message, etc..). Alerts may have to be acknowledged by the User. The EEVBS will collapse alerts into a single alert to avoid creating too many that would be annoying. Alerts are almost always generated from Events. Alerts are commonly generated when Cameras are turned off, go offline, or when motion is detected in areas where there should not be any motion. The Alert may or may not include the video or other Assets of interest. Alerts sent to Users automatically create a Save to provide organized access to the related image, video, and meta-data. The URL to the save is provide within the Alert for immediate access. (THIS IS PROBABLY ACTUALLY A SHARE, A GROUP OF SAVES, SINCE ALERTS USUALLY “CLUSTER”)

Alert Events
Alert Events are Events that are known to generate an Alert.

Motion Detection Region
Each camera can have 1 or more Motion Detection Regions. These are areas where motion detection will be performed. Normally if there is motion in ANY Motion Detection Region video recording will be enabled. Motion Detection in any region will always generate an Event. The Events will generate Alerts if the User has configured it to generate Alerts on that Motion Detection Region.

Privacy Region
A Camera may have 1 or more Privacy Regions defined. This is a mask where all Asset images and video are blanked out.

Meta Data Assets
This is data that identifies items in the Video Assets. Used to identify faces, license plates, activity, motion, and other items that are happening in the video Assets

Audit Trail
All changes and activities by each user are recorded for audit trail. These items are stored on a per user basis. Things stored included: all configuration changes, all camera configuration changes (PTZ), all video’s viewed, all camera adds and deletes, all manual recordings, all changes to schedule, all changes to alerts.

Retention Policy
Every Camera has associated with it a retention policy. The retention policy indicates how much and how long the Assets (the video) from the Camera should be retained. The Account has a Default Retention Policy which is used for all Cameras in that account. This Policy can be overridden on a per Camera basis.

Timestamps
All Assets have attached a Timestamp. The Timestamp records when the Asset happened. Timestamps are always in UTC and maintained to the nearest millisecond. Timestamps are rendered in text as YYYYMMDDhhmmss.mmm. Timestamps are represented numerically as milliseconds from the epoch (Jan 1 1970… same as time(), gettimeofday etc. on Linux, timestamps in Javascript etc.).

EE Director
The Director is the URL first contacted when a camera is connecting with the EEVBS. The Director performs verification of access, provides account information, and lists of Cameras in an Account. Given a Camera ID it provides the URL of the appropriate EE Archiver(s) that have the Assets of the requested Camera so the application in question can get them for display. http://d.eagleeyenetworks.com. Cameras also contact the EE Director to determine where they should send their Assets.

EE GUI
Webservers that serve up the HTTP Javascript User interface to control and view Cameras. http://v.eagleeyenetworks.com This user interface is built on the EEVB API.

EE Archiver
The architectural element that communicates with the Cameras and stores all the Assets. It serves up the Assets to the EE GUI as well as the iOS App and Android App. EE Archivers are accessed via IP address.

EE Locator
The EE Locator has a fixed IP address that does not change. Camera and Bridges when they first installed attempt to contact the EE Locater using DNS at first, but then a fixed IP address if DNS does not work. The EE Locator provides the camera its Camera ID, authenticates it, and directs it to the appropriate Archiver and other connections it will need to communicate with the EEVB. If the Locator goes down, the only function that will stop working is adding new Cameras.

Client
A client is a software application that interfaces with the EEVBS to display assets, make changes, or do analysis.

Bridge
The Bridge is a product of Eagle Eye that sits at the customer location and talks to industry standard cameras. It converts the Cameras to be compatible with the EEVB and record the Assets. The Bridge is setup and controlled via a cloud based user inteface. There is no user interface on the Bridge. The Bridge may serve local Assets directly to local Clients. The Bridge will also store Assets until they are transferred to the EEVB. The Bridge may be configured via DHCP or with a static IP address.