Evercam.io API

Welcome to the Evercam V1 API documentation. Here you'll find all the API references and links to client libraries that you'll need to get

Base URI

https://api.evercam.io/v1
Documentation
API Authentication

The evercam REST API supports multiple different authentication mechanisms to ensure that whatever environment you find yourself in, we've got you covered. This section of the documentation outlines the various methods available.

Basic

To make it as easy as possible for developers to quickly test and learn the various resource actions available we've enabled HTTP basic authentication using your username (or email) and password. The following cURL command illustrates this authentication method.

curl -X GET https://api.evercam.io/v1/... \
-u {username}

Session

As evercam utilises cookies to maintain a users session once they have been logged in, any ajax requests originating from the same user agent can be told to include the apprioriate credentials. This can be achieved in jQuery in the following way:

jQuery.ajax({
  url: 'https://api.evercam.io/v1/...',
  xhrFields: {
    withCredentials: true
  },
  statusCode: {
    200: {
      ...
    },
    ...
  },
  ...
});

OAuth 2.0

Implicit Grant

Our implementation supports the implicit grant type which can be used to obtain access tokens. It is optimised and secured for clients with a predetermined set of redirect uris. Typically this means a browser using javascript. It is a redirection-based flow which, when successfully authorized, results in the browser being directed back to the client application with an access token appended to the fragment portion of the redirect uri. The process starts with the client (you) redirecting the user (their browser) to our authorization endpoint with the following querystring parameters. Values surrounded with curly braces { } are required, those surrounded by square brackets [ ] are optional.

https://www.evercam.io/oauth2/authorize...

?response_type=token
&client_id={your evercam client id}
&scope={the access scopes you wish to use}
&redirect_uri=[one of your registered callback uris] // optional
&state=[a value you choose to help prevent CSRF] // optional

If the user has previously granted your application access to all the resources requested in the scope parameters, or if the user chooses to now authorize those scopes, evercam will generate a new access token and redirect the user back to the either the redirect_uri parameter you provided or to the default callback uri associated with your client account when you registered. The access token and its duration will be appended as part of the uri fragment as follows:

https://{redirect_uri}#access_token=410d79341e45c915&token_type=bearer&expires_in=3600

If the user declines your authorization request or if your request is malformed or invalid then the user will be redirected back to the {redirect_uri} (or default callback uri) with an error status and message as follows:

https://{redirect_uri}#error=access_denied&error_description=some+error+message&state={your state}

Should the client_id parameter be invalid or the redirect_uri parameter not match one of the values you have registered with your account then the user will be shown an error on the evercam site.

Evercam.js

Evercam.js

Evercam.js allows you to easily access all evercam.io APIs and also works as jQuery plugin which can easily show image from any evercam-enabled camera on a website. jQuery is dependency and it has to be included before evercam.js.

Including Evercam.js

Edit your HTML page and put following two lines inside head tag

<script src="http://ajax.googleapis.com/ajax/libs/jquery/2.0.3/jquery.min.js"></script>
<script src='http://cdn.evercam.io/js/v1/evercam.js'></script>
So it will look like this:
<!DOCTYPE html>
<html>
<head>
  <title></title>
  <script src="http://ajax.googleapis.com/ajax/libs/jquery/2.0.3/jquery.min.js"></script>
  <script src='http://cdn.evercam.io/js/v1/evercam.js'></script>
</head>
<body>

</body>
</html>

Showing camera snapshots

Via attributes

Simplest way to show image from camera on your website is to just add img tag with evercam specific attributes. Evercam.js will automatically load camera image into img tag with 'evercam' attribute set to stream name and refresh it every X seconds times 1000 (set in 'refresh' attribute). Typical camera image resolution is 640x480 pixels but you can adjust it to your needs using width and height parameters. Following line of code will get new snapshot from camera every 5 seconds and display it as 320x240 pixels image:

<img evercam='dublin-rememberance-floor2' width="320" height="240" refresh='5000' />
Following html page will display camera image on full screen and update it every 2 seconds:
<!DOCTYPE html>
<html>
<head>
<title></title>
  <script src="http://ajax.googleapis.com/ajax/libs/jquery/2.0.3/jquery.min.js"></script>
  <script src='http://cdn.evercam.io/js/v1/evercam.js'></script>
</head>
<body>
  <img evercam='dublin-rememberance-floor2' width="100%" height="100%" refresh='2000' />
</body>
</html>
Via JavaScript

Load camera image into jQuery selector by calling evercam method with 'snapshot' as first argument and options dictionary as second.

$(img).evercam('snapshot', {
  name: name,
  refresh: refreshRate
});

Following code will get new snapshot from camera every 5 seconds and display it as 320x240 pixels image:

$(img).evercam('snapshot', {
  name: 'dublin-rememberance-floor2',
  refresh: 5000
}).width(320).height(240);
API Methods
GET /test.{format}
Users
GET /users/{id}/cameras.{format}
POST /users.{format}
GET /users/{id}/rights.{format}
GET /users/{id}.{format}
PATCH /users/{id}.{format}
GET /users/{id}/credentials.{format}
DELETE /users/{id}.{format}
User's cameras
GET /users/{id}/cameras.{format}

Returns the set of cameras owned by a particular user

Path variables

id
string required

Responses

Create account
POST /users.{format}

Starts the new user signup process

Request parameters

forename
string required

Forename.

lastname
string required

Lastname.

username
string required

Username.

country
string required

Country.

email
string required

Email.

password
string required

Password.

Responses

Rights list
GET /users/{id}/rights.{format}

Returns the set of camera and other rights you have granted and have been granted (COMING SOON)

Path variables

id
string required

Responses

200 OK
User info
GET /users/{id}.{format}

Returns available information for the user

Path variables

id
string required

Responses

200 OK
Update account
PATCH /users/{id}.{format}

Updates full or partial data on your existing user account

Path variables

id
string required

Username.

Request parameters

forename
string optional

Forename.

lastname
string optional

Lastname.

username
string optional

Username.

country
string optional

Country.

email
string optional

Email.

Responses

User credentials
GET /users/{id}/credentials.{format}

Fetch API credentials for an authenticated user.

Path variables

id
string required

User name for the user to fetch credentials for.

Request parameters

password
string required

Password for the user to fetch credentials for.

Responses

200 OK
Delete account
DELETE /users/{id}.{format}

Delete your account, any cameras you own and all stored media

Path variables

id
string required

Responses

Cameras
GET /cameras/test.{format}
GET /cameras/{id}.{format}
PATCH /cameras/{id}.{format}
POST /cameras.{format}
DELETE /cameras/{id}.{format}
GET /cameras/{id}/shares.{format}
POST /cameras/{id}/share.{format}
DELETE /cameras/{id}/share.{format}
PATCH /cameras/share/{id}.{format}
GET /cameras/{id}/snapshots.{format}
POST /cameras/{id}/snapshots.{format}
GET /cameras/{id}/snapshots/latest.{format}
GET /cameras/{id}/snapshots/range.{format}
GET /cameras/{id}/snapshots/{year}/{month}/days.{format}
GET /cameras/{id}/snapshots/{year}/{month}/{day}/hours.{format}
GET /cameras/{id}/snapshots/{timestamp}.{format}
POST /cameras/{id}/snapshots/{timestamp}.{format}
DELETE /cameras/{id}/snapshots/{timestamp}.{format}
GET /cameras/{id}/snapshot.jpg.{format}
Test camera params
GET /cameras/test.{format}

Tests if given camera parameters are correct

Request parameters

external_url
string required

External camera url.

jpg_url
string required

Snapshot url.

cam_username
string required

Camera username.

cam_password
string required

Camera password.

Responses

Camera information
GET /cameras/{id}.{format}

Returns all data for a given camera

Path variables

id
string required

Responses

Update camera
PATCH /cameras/{id}.{format}

Updates full or partial data for an existing camera

Path variables

id
string required

Camera Id.

Request parameters

name
string optional

Camera name.

is_public
unknown optional

Is camera public?

external_host
string optional

External camera host.

internal_host
string optional

Internal camera host.

external_http_port
string optional

External camera http port.

internal_http_port
string optional

Internal camera http port.

external_rtsp_port
string optional

External camera rtsp port.

internal_rtsp_port
string optional

Internal camera rtsp port.

jpg_url
string optional

Snapshot url.

cam_username
string optional

Camera username.

cam_password
string optional

Camera password.

Responses

New camera
POST /cameras.{format}

Creates a new camera owned by the authenticating user

Request parameters

id
string required

Camera Id.

name
string required

Camera name.

is_public
unknown required

Is camera public?

external_host
string optional

External camera host.

internal_host
string optional

Internal camera host.

external_http_port
number optional

External camera http port.

internal_http_port
number optional

Internal camera http port.

external_rtsp_port
number optional

External camera rtsp port.

internal_rtsp_port
number optional

Internal camera rtsp port.

jpg_url
string optional

Snapshot url.

cam_username
string optional

Camera username.

cam_password
string optional

Camera password.

Responses

Delete camera
DELETE /cameras/{id}.{format}

Deletes a camera from Evercam along with any stored media

Path variables

id
string required

Responses

List shares
GET /cameras/{id}/shares.{format}

Get the list of shares for a specified camera

Path variables

id
string required

The unique identifier for a camera.

Responses

New share
POST /cameras/{id}/share.{format}

Create a new camera share

Path variables

id
string required

Request parameters

email
string required

Email address of user to share the camera with.

rights
string required

A comma separate list of the rights to be granted with the share.

message
string optional

Not currently used.

String
string optional

Not currently used.

notify
unknown optional

Not currently used.

Responses

Delete share
DELETE /cameras/{id}/share.{format}

Delete an existing camera share

Path variables

id
string required

The unique identifier for a camera.

Request parameters

share_id
number required

The unique identifier of the share to be deleted.

Responses

200 OK
Update share
PATCH /cameras/share/{id}.{format}

Update an existing camera share (COMING SOON)

Path variables

id
string required

Responses

200 OK
List snapshots
GET /cameras/{id}/snapshots.{format}

Returns the list of all snapshots currently stored for this camera

Path variables

id
string required

Camera Id.

Responses

200 OK
Create a snapshot
POST /cameras/{id}/snapshots.{format}

Fetches a snapshot from the camera and stores it using the current timestamp

Path variables

id
string required

Camera Id.

Request parameters

notes
string optional

Optional text note for this snapshot

Responses

200 OK
Get latest snapshot
GET /cameras/{id}/snapshots/latest.{format}

Returns latest snapshot stored for this camera

Path variables

id
string required

Camera Id.

Request parameters

with_data
unknown optional

Should it send image data?

Responses

Filter snapshots
GET /cameras/{id}/snapshots/range.{format}

Returns list of snapshots between two timestamps

Path variables

id
string required

Camera Id.

Request parameters

from
number required

From Unix timestamp.

to
number required

To Unix timestamp.

with_data
unknown optional

Should it send image data?

limit
number optional

Limit number of results, default 100 with no data, 10 with data

page
number optional

Page number

Responses

200 OK
Get days with snapshots
GET /cameras/{id}/snapshots/{year}/{month}/days.{format}

Returns list of specific days in a given month which contains any snapshots

Path variables

id
string required

Camera Id.

year
number required

Year, for example 2013

month
number required

Month, for example 11

Responses

200 OK
Get hours in a day with snapshots
GET /cameras/{id}/snapshots/{year}/{month}/{day}/hours.{format}

Returns list of specific hours in a given day which contains any snapshots

Path variables

id
string required

Camera Id.

year
number required

Year, for example 2013

month
number required

Month, for example 11

day
number required

Day, for example 17

Responses

200 OK
Get closest snapshot
GET /cameras/{id}/snapshots/{timestamp}.{format}

Returns the snapshot stored for this camera closest to the given timestamp

Path variables

id
string required

Camera Id.

timestamp
number required

Snapshot Unix timestamp.

Request parameters

with_data
unknown optional

Should it send image data?

range
number optional

Time range in seconds around specified timestamp

Responses

Save snapshot
POST /cameras/{id}/snapshots/{timestamp}.{format}

Stores the supplied snapshot image data for the given timestamp

Path variables

id
string required

Camera Id.

timestamp
number required

Snapshot Unix timestamp.

Request parameters

data
unknown required

Image file.

notes
string optional

Optional text note for this snapshot

Responses

200 OK
Delete snapshot
DELETE /cameras/{id}/snapshots/{timestamp}.{format}

Deletes any snapshot for this camera which exactly matches the timestamp

Path variables

id
string required

Camera Id.

timestamp
number required

Snapshot Unix timestamp.

Responses

200 OK
Get JPG
GET /cameras/{id}/snapshot.jpg.{format}

Returns jpg from the camera

Path variables

id
string required

Camera Id.

Responses

200 OK
Camera Models
GET /models.{format}
GET /models/{vendor}.{format}
GET /models/{vendor}/{model}.{format}
Supported camera vendors
GET /models.{format}

Returns set of support supported camera vendors

Responses

Vendor's models
GET /models/{vendor}.{format}

Returns set of known models for a supported camera vendor

Path variables

vendor
string required

Responses

Camera info
GET /models/{vendor}/{model}.{format}

Returns data for a particular camera model

Path variables

vendor
string required
model
string required

Responses

Vendors
GET /vendors.{format}
GET /vendors/{mac}.{format}
List all vendors
GET /vendors.{format}

Returns all known IP hardware vendors

Responses

Filter vendors
GET /vendors/{mac}.{format}

Returns all known IP hardware vendors filtered by MAC prefix

Path variables

mac
string required

Responses

Test API credentials
GET /test.{format}

A simple endpoint that can be used to test whether an API id and key pair are valid.

Request parameters

api_id
string optional

The API id to be tested.

api_key
string optional

The API key to be tested.

Responses

200 OK
Data Reference
Evercam::Presenters::Camera
Object
id
string

Unique Evercam identifier for the camera

name
string

Human readable or friendly name for the camera

owner
string

Username of camera owner

vendor
string

Unique identifier for the camera vendor

model
string

Name of the camera model

created_at
number

Unix timestamp at creation

updated_at
number

Unix timestamp at last update

last_polled_at
number

Unix timestamp at last heartbeat poll

last_online_at
number

Unix timestamp of the last successful heartbeat of the camera

timezone
string

Name of the IANA/tz timezone where this camera is located

is_online
boolean

Whether or not this camera is currently online

is_public
boolean

Whether or not this camera is publically available

external_host
string

External host of the camera

internal_host
string

Internal host of the camera

external_http_port
number

External http port of the camera

internal_http_port
number

Internal http port of the camera

external_rtsp_port
number

Internal rtsp port of the camera

internal_rtsp_port
number

External rtsp port of the camera

jpg_url
string

Snapshot url

cam_username
string

Camera username

cam_password
string

Camera password

mac_address
string

The physical network MAC address of the camera

location
unknown

GPS lng and lat coordinates of the camera location

Evercam::Presenters::User
Object
id
string

Unique Evercam username

created_at
number

Unix timestamp at creation

updated_at
number

Unix timestamp at last update

confirmed_at
number

Unix timestamp at account confirmation

forename
string

Users forename

lastname
string

Users lastname

username
string

Unique Evercam username

email
string

Users email address

country
string

Two letter ISO country code

Evercam::Presenters::Vendor
Object
id
string

Unique identifier for the vendor

name
string

Name of the vendor

known_macs
Array of string

String array of MAC prefixes the vendor uses

is_supported
boolean

Whether or not this vendor produces Evercam supported cameras

models
Array of string

String array of models currently known for this vendor

Evercam::Presenters::Model
Object
vendor
string

Unique identifier for the vendor

name
string

Name of the model

known_models
Array of string

String array of all models known to share the same defaults

defaults
unknown

Various default values used by this camera model

Methods: Camera info
Evercam::Presenters::CameraShare
Object
id
number

Unique identifier for a camera share.

camera_id
string

Unique identifier of the shared camera.

user_id
number

Unique user id of the user the camera is shared with.

email
string

The email address of the user the camera is shared with.

kind
string

Either 'public' or 'private' depending on the share kind.

rights
string

A comma separated list of the rights available on the share.

Evercam::Presenters::Snapshot
Object
camera
string

Unique Evercam identifier for the camera

notes
string

Note for snapshot

created_at
number

Snapshot timestamp

timezone
string

Name of the IANA/tz timezone where this camera is located

data
unknown

Image data