Welcome

The Camio API makes it simple to add real-time video search to any camera, NVR, VMS, website or service. Also see ifttt.com/camio for ways that non-programmers can script Camio’s interaction with other services. Please let us know how we can improve either this documentation or the Camio API itself. Thanks.

Root Endpoint

The root API endpoint for all API commands is:

https://camio.com/api

All timestamps use the ISO8601 format:

YYYY-MM-DDTHH:MM:SS.mmmZ like 2016-01-21T20:38:31.469-0700

The Basics

Most developers want a quick way to record video, perform an action when something important happens, and see what’s recorded. So here’s a quick intro to those three uses of the Camio API.

Recording Video and Images

Example requests to record video and images:

curl \
    -H "Content-Type: video/mp4" \
    -X PUT \
    -T "2014-07-21T20:38:31.000-07:00.mp4" \
    https://camio.com/api/users/51r6kndapc/cameras/front/content/2014-07-21T20:38:31.000-07:00.mp4?camera_id=1234&upload_mode=video

curl \
    -H "Content-Type: image/jpeg" \
    -X PUT \
    -T "2014-07-21T20:38:32.183-07:00.jpeg" \
    https://camio.com/api/users/51r6kndapc/cameras/front/content/2014-07-21T20:38:32.183-07:00.jpeg?camera_id=1234

You can record with any network camera using camio.com/start.

But you can also programmatically connect any other source of video/images using the API to upload camera content. For example, the command on the right uploads a motion-triggered snapshot to a camera named front using the Upload Token 51r6kndapc.

Note that no Authorization HTTP Header is needed. Your Upload Token itself grants permission to upload only - without granting permission to access content.

These examples upload directly to the cloud, however Camio Box is the bandwidth-efficient way to ingest video, because the video can be analyzed on your local network before deciding whether and how to upload it. Download Camio Box VM for free, and use its POST /api/content API locally instead.

Registering Callbacks

curl \
    -H "Content-Type: application/json" \
    -H "Authorization: token xyzauthtoken" \
    -d '{"callback_url": "http://example.com/camio/package-delivery", "type": "query_match", "query": {"text": "people approaching mailbox in front"}}' \
    -X POST https://camio.com/api/users/me/hooks

Hooks enable you to take an action whenever particular events happen. For example, use the curl command on the right to create a hook requesting that:

• whenever an important event matches the query people approaching mailbox in front
• execute HTTPS POST http://example.com/camio/package-delivery with the json payload describing the triggering event.

Seeing Recorded Content

An example of an iframe:

<iframe src="https://camio.com/c/b1bqks3l76yo&key=123abc&autoplay=false&embedded=true" width="603" height="452" frameBorder="0"></iframe>

You can use the Camio Browser, iOS, and Android apps to view recorded content, or you can write your own viewers using the low-level Search API. But if you’d like to embed content on your site easily, you can use an iframe as in this example of the mischievous dog Kody:

HTML

<iframe src="https://camio.com/c/:view_token&key=:key" width="603" height="452" frameBorder="0"></iframe>

URL Parameters

Name	Description	Details
view_token	The view token that authorizes access to the Camio	string, required, example: b1bqks3l76yo
key	Your Camio API Key. All requests must include your API Key as the value of the key parameter so that Camio can contact you about your website/application usage if necessary	string, required, example: 123abc
autoplay	The default value is true, but set to false to prevent the embedded video from playing automatically.	boolean, optional, example: false
embedded	Set to true if the automatic detection isn’t working for any reason.	boolean, optional, example: true

Authentication

OAuth

To authorize a cURL request, for example, use this code:

# With cURL, you can just pass the correct header with each request
curl "https://camio.com/api/users/me/cameras" \
    -H "Authorization: token OAUTH-TOKEN"

Be sure to replace OAUTH-TOKEN with your OAuth token.

Camio uses OAuth tokens to provide access to the API.

You can obtain a development OAuth token by using the Generate button at https://camio.com/settings/integrations/#api.

Authorization Header

Camio expects the token to be included in all API requests to the server in an HTTP header like:

Authorization: token OAUTH-TOKEN

Authorization Parameter

The Authorization Header is the preferred method of authentication with an OAuth token. But alternatively, the access_token query parameter can specify the OAuth token.

https://camio.com/api/search/?text=Entry&access_token=OAUTH-TOKEN

Developer OAuth Token

Your application normally obtains the value for OAUTH-TOKEN from the user’s granting permission via the OAuth flow. For initial development, you can replace OAUTH-TOKEN with your Developer OAuth token.

How to obtain and OAuth Token

Redirect users to request Camio access

GET https://camio.com/api/login/oauth/authorize

URL Parameters

Name	Description	Details
client_id	The client id you received from Camio.	string, required, example: abc123
redirect_uri	The URL in your app where users will be sent after authorization. This url must accept the query parameter &code=:code.	string, optional, example https://www.example.com/camio/oauth
scope	Comma separated list of scopes. Default scope is user.	string, optional.
state	An unguessable random string. It is used to protect against cross-site request forgery attacks.	string, optional.

Camio redirects back to your site

If the user accepts your request, Camio redirects back to your site with a temporary code in a code parameter as well as the state you provided in the previous step in a state parameter. If the states don’t match, the request has been created by a third party and the process should be aborted. Exchange this for an access token with:

POST https://camio.com/api/login/oauth/access_token

URL Parameters

Name	Description	Details
client_id	The client id you received from Camio.	string, required, example: abcdefg
redirect_uri	The URL in your app where users will be sent after authorization. This url must accept the query parameter &code=:code.	string, optional, example https://www.example.com/oauth
client_secret	The client secret you received from Camio when you registered.	string, required.
code	The code you received as a response to the prior step.	string, required.

Response

By default, the response will take the following form: access_token=e72e16e429212e7710c838347ae178b4a&token_type=bearer

You can also receive the content in different formats depending on the Accept header: Accept: application/json {"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a","token_type":"bearer"}

Use the access token to access the API

The access token allows you to make requests to the API on a behalf of a user. Currently, you must supply the access token in the HTTP Authorization header for POST/PUT/PATCH commands. For HTTP GET commands, you can supply &access_token= as an url parameter.

For example, an HTTP POST would use: $ curl -H "Authorization: token abcdefg" https://camio.com/api/users/me/cameras

and an HTTP GET would use: GET https://www.camio.com/api/users/me/cameras?access_token=abcdefg

OAuth Scopes

Camio scopes are expressed as the object to which they grant access followed by the class of actions they allow (e.g. settings:write). If the class of action is omittted, then the scope is for all actions on the object.

There are currently only two classes of actions:

1. read: Reading the full information about a single resource.
2. write: Modifying the resource in any way e.g. creating, editing, or deleting.

Scope	Description
user	full access to act as the user.
settings	read and write access to all settings.
settings:write	write access to all settings.
setttings:read	read access to all settings.
settings:recording	read and write access to turn recording ON/OFF.
settings:recording:write	write access to turn recording ON/OFF.
settings:recording:read	read access to recording ON/OFF.

If your application requires some other scope, just let us know.

CSRF protection

Camio protects against Cross Site Request Forgery (CSRF) by verifying that all requests that rely on browser cookies as the method of authentication also include in the HTTP Header X-Csrf-Token value that matches the value supplied by the cookie csrfToken. The value for the cookie named csrfToken is returned from the browser’s prior OAuth request.

Non-browser API requests (e.g. those sent without cookies via curl), rely only on the Authorization: token YOUROAUTHTOKEN HTTP Header and aren’t required to pass any CSRF checks.

Upload Token

You can also upload content without using OAuth by using your Upload Token instead (found on the page camio.com/token). An Upload Token permits only the uploading of content to your account - without any permission to access your account. That way, the camera source itself has no sign-in credentials on it.

Domain Admin Login

An example login request is:

curl \
    -H "Authorization: token xyzpdq-admin-user" \
    -d '{"client_id":"acme.com", email":"dallas@acme.com","password":"G0Faster","login_type":"oauth"}'
    -X PUT https://camio.com/api/login \

The JSON response is:

{
    "access_token": "h4MPpoECZBYVXkq6mggf2sjAAccwd4Gq",
    "client_id": "acme.com",
    "scopes": [
        "user"
    ],
    "token_type": "bearer",
    "user": {
        "user_id": "cc:5619223886242146851567"
    }
}

The adminstrator of a white-listed domain can skip the OAuth permission flow when logging in to accounts belonging to that same domain. Contact us to enable this feature for your domain.

The client_id value of the domain itself (“acme.com” in this example) indicates that the authenticated domain administrator wants the token for another user on the domain without affecting the administrator’s own login. The domain adminstrator remains logged-in even after the request completes.

VERY IMPORTANT: There is only a single valid OAuth access_token for the domain’s client_id at any moment in time. Each request to /api/login using the domain as client_id invalidates any previous access_token that was granted for that client_id. That means that all of the API clients that are using the access_token issued for the domain’s client_id (e.g. “acme.com” in this example), must begin using the newly issued access_token immediately after it has been issued.

HTTP Request

PUT https://camio.com/api/login

Body

The JSON payload has the following fields.

Name	Description	Details
email	The email address of the user being logged-in.	string, required, example: dallas@acme.com
password	The password of the user being logged-in.	string, required, example: G0Faster
login_type	Only the value oauth is supported.	string, required.
client_id	Required for domain admin requests in order to avoid invalidating the normal login of a domain user.	string, optional, example: acme.com

Cameras

Camio really thinks of a “camera” simply as a video stream. For example, in addition to standalone IP cameras, a “camera” may also be an NVR/VMS channel or a sequence of imported video files.

List connected Cameras

The JSON response is:

[
    {
        "name": "Chrome",
        "attribution": {},
        "tags": [],
        "refreshInterval": 0,
        "camera_id": "ET22dbt2iGBzsaN4u",
        "is_online": true,
        "capabilities":["web_rtc","audio","video"]
    },
    {
        "name": "front",
        "attribution": {},
        "tags": [],
        "is_online": false,
        "capabilities":[]
    },
    {
        "name": "iPad",
        "attribution": {},
        "camera_id":"YY271ZZZ0128XXX",
        "is_online": true,
        "capabilities":["web_rtc","audio","video"]
    }
]

Lists all of the cameras currently connected to the account (exclusive of any other cameras discovered but not yet actually connected).

HTTP Request

GET https://camio.com/api/users/me/cameras/

Query Parameters

Name	Description	Details
fetch_zones	true if you wish to recieve a list of camera zones along with each camera.	string, optional, example: true
user	The email address of the host account that the camera are to be fetched for.	string, optional, example: test@example.com

The boolean field is_online in each Camera object returned, is used to indicate whether the camera is considered to be online by the server or not. The server’s determination of online status takes into account state polls as well as recent uploads. Only the field name is guaranteed to be included with each Camera object returned by the API.

Get a connected Camera

The JSON response is:

{
    "camera_id": "2431614740321587915",
    "attribution": {},
    "capabilities": [
        "web_rtc",
        "audio",
        "video",
        "per_camera_settings",
        "name_changeability"
    ],
    "is_online": true,
    "latitude": 0.0,
    "longitude": 0.0,
    "name": "Door",
    "resolution": {
        "aspect_ratio": 1.7777778,
        "height": 720,
        "width": 1280
    },
    "session_id": "-MTBMEl-fg",
    "tags": [],
    "user_id": "xyzpdq0798386757677"
}

HTTP Request

GET https://camio.com/api/users/me/cameras/:camera

URL Parameters

Name	Description	Details
camera	The name of the camera.	string, required, example: front

The boolean field is_online in the Camera object returned is used to indicate whether the camera is considered to be online by the server or not. The server’s determination of online status takes into account state polls as well as recent uploads. The resolution of the camera is known only after the camera has uploaded content.

List Cameras

Example command is:

curl \
    -H "Authorization: token xyzauthtoken" \
    https://camio.com/api/cameras/discovered?user=owner%40example.com

Sample JSON response is a dictionary keyed by local_camera_id:

{
    "00E04CC27D05.0": {
        "device_user_agent":"CamioBox (Linux; rpi3) Firmware:box-rpi3-cam.201609042236-de4a0cdd7f4ec789059d5ef79023b3070cdc359f",
        "local_camera_id" : "00E04CC27D05.0",
        "mac_address":"00E04CC27D05",
        "name":"Front",
        "user_id":"105730904519723370437",
        ...
    },
    ...
}

This dicionary of cameras represents all the candidate video streams you might connect to Camio. You can think of it as a scratchpad of stream definitions with all the parameters required to connect and process the stream. It’s keyed by the local_camera_id assigned by Camio Box.

HTTP Request

GET https://camio.com/api/cameras/discovered

Query Parameters

Name	Description	Details
user	The email address of the host account.	string, optional, example: owner@example.com

Create Camera

An example request is:

curl \
    -H "Content-Type: application/json" \
    -H "Authorization: token xyzauthtoken" \
    -d '{}' \
    -X POST https://camio.com/api/cameras/discovered

An example JSON payload for the request is:

{
    "0123456789AB.0": {
        "actual_values": {
            "password": {
                "is_multiselect": false,
                "options": [
                    {
                        "name": "opensesame",
                        "value": "opensesame"
                    }
                ]
            },
            "recording_schedule": {
                "is_multiselect": false,
                "options": [
                    {
                        "name": "9pm to 6am",
                        "value": "9pm to 6am"
                    }
                ]
            }
        },
        "default_values": {
            "password": {
                "is_multiselect": false,
                "options": [
                    {
                        "name": "admin",
                        "value": "admin"
                    }
                ]
            },
            "channel": {
                "is_multiselect": false,
                "options": [
                    {
                        "name": "Channel 1",
                        "value": "1"
                    },
                    {
                        "name": "Channel 2",
                        "value": "2"
                    }                       
                ]
            },
            "username": {
                "is_multiselect": false,
                "options": [
                    {
                        "name": "admin",
                        "value": "admin"
                    }
                ]
            }
        },
        "device_id": "d123abc",
        "ip_address": "192.168.1.23",
        "local_camera_id": "0123456789AB.0",
        "mac_address": "0123456789AB",
        "maker": "Sharx",
        "model": "SCNC3905",
        "name": "front",
        "rtsp_server": "rtsp://:@:"
        "rtsp_path": "/live//h264.sdp",
        "should_config": true
    }
}

This API endpoint is for creating cameras that will be connected to Camio via camio.com/box only.

Camio Box scans its local network to discover camera streams automatically. However, this /api/cameras/discovered endpoint is also available for programmatic control over the streams available to be connected to Camio.

To create a camera, specify the way to obtain its video. Camio works with any H.264 video stream from any camera, DVR, NVR, or VMS. There are two methods of acquiring video (aka acquisition_method):

1. rtsp: the live rtsp video stream is processed in real-time.
2. batch: video files are processed in bulk as files.

HTTP Request

POST https://camio.com/api/cameras/discovered

FYI, the POST behaves like a PATCH for the convenience of updating the camera using partially complete information.

JSON Payload

The POST payload is a dictionary keyed by the local_camera_id that the caller assigns to each camera. The required device_id value is obtained from having registered a Camio Box.

The required fields differ based on the value of acquisition_method.

Common fields (regardless of value of acquisition_method)

Name	Description	Details
actual_values	The dictionary of variable values to be used for mustache template substitutions.	object, required if any fields rely on mustache variables.
default_values	The dictionary of default variable values to be used in the absence of a value supplied in actual_values.	object, optional for user convenience in choosing among pre-defined values.
device_id	The device_id of the Camio Box through which this camera is connected to Camio.	string, required only when initially connecting the camera.
name	The user-facing name of the camera, which must be unique within a single user’s account.	object, required only when initially connecting the camera.
should_config	TO BE REFACTORED, but currently true to connect the camera to the device_id and false to disconnect it.	boolean, required.

The actual_values dictionary records the values assigned to various keys required to connect a video stream to Camio. The format of both actual_values and default_values is intended to support single or multiple choice selections shown on the camio.com/boxes page. The mustache variables included in an RTSP URL can reference any of the keys of the actual_values dictionary.

actual_values

The actual_values object is an arbitrary dictionary of variable values to be used in configuring the connection of a video stream to Camio services. Though you can add any key/value pair to this dictionary, the keys described below are the most commonly used.

Each entry in defaults_values has a structure like this:

{
    "face_recognition": {
        "is_multiselect": false,
        "options": [
            {
                "name": "Ignore faces",
                "value": "none"
            },
            {
                "name": "Detect faces",
                "value": "face_detection"
            },
            {
                "name": "Recognize faces",
                "value": "face_recognition"
            }
        ]
    }
}

The actual_values entries include only the single assigned value:

{
    "face_recognition": {
        "is_multiselect": false,
        "options": [
            {
                "name": "Ignore faces",
                "value": "none"
            }
        ]
    }
}

Name	Description	Details
username	The username required to accesss a particular RTSP stream.	string, required when is a mustache variable.
password	The password required to accesss a particular RTSP stream.	string, required when is a mustache variable.
stream	The stream identifier when required to differentiate among multiple streams available.	string, required when is a mustache variable.
channel	The NVR channel identifier when required to differentiate among multiple channels available.	string, required when is a mustache variable.
port	The port used by the camera/NVR/VMS to serve the RTSP stream.	string, required only when is a mustache variable.
plan	The id of the subscription plan for the stream.	string, optional.
disable_audio	Set value to "true" to strip the audio from the stream prior to storage.	string, optional.
face_recognition	Set to "none", "face_detection", or "face_recognition".	string, optional.
face_recognition_min_pixels_per_foot	Set to the minimum number of Pixels Per Foot (PPF) required to trigger attempts to recognize faces	string, optional.
recording_schedule	The time range during which Events are stored immediately in the cloud. In the absence of a recording_schedule value, all Events are stored in the cloud by default.	string, optional. e.g. “9pm to 6am” records nightly from 9pm until 6am the following day.

Required fields for "acquisition_method": "rtsp"

Name	Description	Details
device_id	The device_id of the Camio Box through which this camera is connected to Camio.	string, required.
local_camera_id	Supplied as a key value in the dictionary, this is the arbitrary and unique id chosen by the caller. It is unique among the caller’s cameras but not necessarily globally unique across users.	string, required.
rtsp_server	The server of the H.264 RTSP stream.	string, required for rtsp, example: rtsp://:@:
rtsp_path	The path to the specific stream on the server.	string, required for rtsp, example: /live//h264.sdp
mac_address	The MAC address of the camera, which is used by Box to update the camera’s ip_address as it changes due to DHCP assigments.	string, required for rtsp.
ip_address	The ip_address of the camera video source.	string, required for rtsp.

Required fields for "acquisition_method": "batch"

Name	Description	Details
device_id	The device_id of the Camio Box through which this camera is connected to Camio.	string, required.
local_camera_id	Supplied as a key value in the dictionary, this is the arbitrary and unique id chosen by the caller. It is unique among the caller’s cameras but not necessarily globally unique across users.	string, required.
acquisition_method	The value batch, which informs the Camio Box associated with device_id to expect video files POSTed	string, required.
mac_address	TO BE REFACTORED AS OPTIONAL; DUMMY VALUE IS OK FOR NOW	string, required (TEMPORARILY).

Update Camera

An example request is:

curl \
    -H "Content-Type: application/json" \
    -H "Authorization: token xyzauthtoken" \
    -d '{"0123456789AB.0": {...}}' \
    -X POST https://camio.com/api/cameras/discovered

An example JSON payload to turn OFF a previously known camera with should_config false:

{
    "0123456789AB.0": {
        "device_id": "d123abc",
        "mac_address": "0123456789AB",
        "local_camera_id": "0123456789AB.0",        
        "should_config": false
    }
}

And to turn it back ON with should_config true:

{
    "0123456789AB.0": {
        "device_id": "d123abc",
        "mac_address": "0123456789AB",
        "local_camera_id": "0123456789AB.0",        
        "should_config": true
    }
}

Update cameras with the same endpoint used to create cameras. The minimal payload is shown in this example of turning a camera OFF and then ON through the use of should_config false (OFF) or true (ON).

The payload is keyed by local_camera_id and only the only fields required to identify the camera are device_id, mac_address, and local_camera_id.

For example, if you’d like to turn cameras ON or OFF based on your own scheduling system, then you’d POST to this endpoint whenever you want to change the single value should_config to true or false (without supplying any other fields beyond those required to identify the camera).

HTTP Request

POST https://camio.com/api/cameras/discovered

The POST behaves like a PATCH for the convenience of updating the camera using partially complete information.

JSON Payload

The POST payload is a dictionary keyed by the local_camera_id that the caller assigns to each camera. The required device_id value is obtained from having registered a Camio Box.

Required fields to identify a camera

Name	Description	Details
device_id	The device_id of the Camio Box through which this camera is connected to Camio.	string, required.
local_camera_id	Supplied as a key value in the dictionary, this is the arbitrary and unique id chosen by the caller. It is unique among the caller’s cameras but not necessarily globally unique across users.	string, required.
mac_address	The MAC address of the camera, which is used by Box to update the camera’s ip_address as it changes due to DHCP assigments.	string, required for rtsp.

The other input fields are described in create cameras.

Delete Camera

The response is:

204 (No Content)

HTTP Request

DELETE https://camio.com/api/users/me/cameras/:camera

URL Parameters

Name	Description	Details
camera	The name of the camera.	string, required, example: front

Get a live stream session

Example request is:

curl \
    -H "Authorization: token xyzauthtoken" \
    https://camio.com/api/cameras/sessions/?local_camera_id=00E04CC27CC8.0&user=sarah%40example.com

JSON response is:

{
    "date_created": "2018-08-14T00:32:15.780-0000",
    "hls_url": "https://hls.camio.com/hls/da98802a-ea1f-40b1-a059-***redacted***",
    "streaming_server_url": "rtmp://hls.camio.com/hls/da98802a-ea1f-40b1-a059-***redacted***",
    "uuid": "da98802a-ea1f-40b1-a059-***redacted***"
}

Use this GET command that returns the hls_url for the HLS live stream. This serves the native stream’s video encoding directly (i.e. there is no reencoding of the stream). The session must have been created previously (see Create a live streaming session ) The streaming_server_url is used only by the Camio Box gateway.

HTTP Request

GET https://camio.com/api/cameras/sessions

URL Parameters

Name	Description	Details
local_camera_id	The local_camera_id of the camera to stream.	string, required.
user	The email address of the user that owns the account.	string, optional.

Create a live streaming session

An example request is:

curl \
    -H "Content-Type: application/json" \
    -d '{"local_camera_id": "00E04CC27CC8.0"}' \
    -X PUT https://camio.com/api/cameras/sessions?user=sarah%40example.com

JSON response is:

{
    "date_created": "2018-08-14T00:32:15.780-0000",
    "hls_url": "https://hls.camio.com/hls/da98802a-ea1f-40b1-a059-***redacted***",
    "streaming_server_url": "rtmp://hls.camio.com/hls/da98802a-ea1f-40b1-a059-***redacted***",
    "uuid": "da98802a-ea1f-40b1-a059-***redacted***"
}

Live streaming sessions remain alive for 20 minutes.

HTTP Request

PUT https://camio.com/api/cameras/sessions

URL Parameters

Name	Description	Details
user	The email address of the user that owns the account.	string, optional.

JSON Payload

Name	Description	Details
local_camera_id	The local_camera_id of the camera to stream.	string, required.

Delete a live streaming session

The curl command is:

curl \
    -H "Authorization: token xyzauthtoken" \
    -X DELETE https://camio.com/api/cameras/sessions/?local_camera_id=00E04CC27CC8.0&user=sarah%40example.com

The response is:

204 (No Content)

Delete the live streaming session.

HTTP Request

DELETE https://camio.com/api/cameras/sessions

URL Parameters

Name	Description	Details
user	The email address of the user that owns the account.	string, optional.

Create a Camera Configuration Request

The cameras referenced in the requests must be connected to a Camio Box.

An example request is:

curl \
    -H "Content-Type: application/json" \
    -d '{"A1A2A3A4A5AA.0":{"local_camera_id": "A1A2A3A4A5AA.0","mac_address": "A1A2A3A4A5AA", "device_id": "BAQF123abc"}}' \
    -X PUT https://camio.com/api/cameras/requests/configuration

The JSON payload is keyed by local_camera_id:

{
    "A1A2A3A4A5AA.0": {
        "local_camera_id": "A1A2A3A4A5AA.0",
        "mac_address": "A1A2A3A4A5AA",
        "device_id": "BAQF123abc"
    }
}

The response is:

204 (No Content)

This automatically applies all camera configuration settings defined by this repo. Only the owner of the account or a Guest with “Can Manage” permission can make this request.

HTTP Request

PUT https://camio.com/api/cameras/requests/configuration (all except WiFi)

PUT https://camio.com/api/cameras/requests/configuration/wifi (WiFi only)

Body

The payload is a dictionary keyed by local_camera_id, and each entry in the JSON dictionary must specify the local_camera_id, mac_address and device_id.

Create a Thumbnail Request

This requests that a new thumbnail be fetched from the specified camera(s).

An example request is:

curl \
    -H "Content-Type: application/json" \
    -d '{"A1A2A3A4A5AA.0":{"local_camera_id": "A1A2A3A4A5AA.0","mac_address": "A1A2A3A4A5AA", "device_id": "BAQF123abc"}}' \
    -X PUT https://camio.com/api/cameras/requests/thumbnails

The JSON payload is keyed by local_camera_id:

{
    "A1A2A3A4A5AA.0": {
        "local_camera_id": "A1A2A3A4A5AA.0",
        "mac_address": "A1A2A3A4A5AA",
        "device_id": "BAQF123abc"
    }
}

The response is:

204 (No Content)

HTTP Request

PUT https://camio.com/api/cameras/requests/thumbnails

Body

The payload is a dictionary keyed by local_camera_id, and each entry in the JSON dictionary must specify the local_camera_id, mac_address and device_id.

Export Cameras

An example request is:

curl \
    -H "Authorization: token abc123" \
    -d '{"account_email":"jane@example.com","filter":"connected"}' \
    -X PUT \
    https://camio.com/api/cameras/exported

The JSON response is:

{
    "account_email": "jane@example.com",
    "download": {
        "method": "GET",
        "url": "https://storage.googleapis.com/camio_import/exported-streams-1175XXXX677-2018-05-29T02:03:55.768-0000?GoogleAccessId=686269513085@developer.gserviceaccount.com&Expires=1527561236&Signature=RpArK09tjmzg%3D"
    },
    "filter": "connected",
    "key": "exported-streams-1175XXXX677-2018-05-29T02:03:55.768-0000",
    "row_count": 6
}

This command exports the definition of cameras for download. The download field in the response includes the url and method required to retrieve the exported cameras.

HTTP Request

PUT https://camio.com/api/cameras/exported

JSON Payload

Name	Description	Details
account_email	The email address of the account owning the camera	string, required, example: jane@example.com
filter	Either connected for only those cameras connected to Camio, recognized for those identified as a camera regardless of whether connected, and none for all devices discovered on your local network.	string, optional, example: connected

Import Cameras

An example request is:

curl \
    -H "Authorization: token abc123" \
    -X PUT \
    https://camio.com/api/cameras/imported

The JSON response is:

{
    "callback": {
        "method": "POST",
        "url": "https://camio.com/api/cameras/imported?token=AQCYtA8Jf6yh0"
    },
    "upload": {
        "content_type": "text/csv",
        "method": "PUT",
        "url": "https://storage.googleapis.com/camio_import/streams-1175XXXX677-2018-05-29T02:25:05.557-0000?GoogleAccessId=686269513085@developer.gserviceaccount.com&Expires=1527562505&Signature=ll%2BX0Pfpm5Tmob%2BmCo%3D"
    }
}

This command creates the upload and callback info required to import a CSV file containing camera definitions. The caller must subsequently perform the following two steps:

1. Use the method and url specified in upload to submit a CSV file with Content-Type content_type.
2. Upon completing the submission, use the method and url specified in callback to notify the server.

HTTP Request

PUT https://camio.com/api/cameras/imported

Labels

List Camera Labels

An example request is:

curl \
    -H "Authorization: token abc123" \
    https://camio.com/api/cameras/labels

The JSON response is:

{
    "Front Door": [
        "California",
        "home",
        "94401",
        "San Mateo"
    ],
    "Office Entrance": [
        "California",
        "work",
        "94043",
        "Mountain View"
    ]
}

Retrieve the dictionary of camera labels keyed by camera_name. If a particular camera_name is supplied as an URL Parameter, then the response is the array of labels for that camera_name only.

URL Parameters

Name	Description	Details
user	The email address of the account owning the camera	string, optional, example: test@example.com
camera_name	The name of a particular camera if only one camera requested	string, optional, example: Front Door

Add Camera Labels

An example request is:

curl \
    -H "Authorization: token abc123" \
    -d '{"Front Door": ["home", "San Mateo"], "Office Entrance":["work"]}' \
    -X POST \
    https://camio.com/api/cameras/labels

The response is:

204 (No Content)

Add the argument camera labels to any existing labels associated with the camera(s). The input JSON is a dictionary keyed by camera_name with values of an array of labels.

URL Parameters

Name	Description	Details
user	The email address of the account owning the camera	string, optional, example: test@example.com

Replace Camera Labels

An example request is:

curl \
    -H "Authorization: token abc123" \
    -d '{"Front Door": ["home", "San Mateo"], "Office Entrance":["work"]}' \
    -X PUT \
    https://camio.com/api/cameras/labels

The response is:

204 (No Content)

Use PUT to replace the camera labels with those specified by the JSON payload, which is a dictionary keyed by camera_name with values of an array of labels.

URL Parameters

Name	Description	Details
user	The email address of the account owning the camera	string, optional, example: test@example.com

Zones

Zones are polygons. Each x,y point is the percentage offset from the Top,Left corner of the scene. (i.e. Top,Left is 0,0 and Bottom,Right is 1,1)

List all Zones

An example request is:

curl \
    -H "Authorization: token abc123" \
    https://camio.com/api/users/me/cameras/Office/zones

The JSON response is:

[
  {
    "name": "door",
    "polygons": [
      {
        "points": [
          {
            "x": 0.12079093470323,
            "y": 0.16636921918746
          },
          ...
        ]
      }
    ]
  },
  {
    "name": "entrance",
    "polygons": [
      {
        "points": [
          {
            "x": 0.45530391629449,
            "y": 0.1171216887084
          },
          ...
        ]
      }
    ]
  }
]

Retrieve a list of all of the zones including their names and the polygons that define them for a specific camera.

HTTP Request

GET https://camio.com/api/users/:user/cameras/:camera/zones

URL Parameters

Name	Description	Details
user	The email address of the account owner or me for the signed-in user.	String, required, example: jane@example.com
camera	The name of the camera.	string, required, example: front

Get Specific Zone

The JSON response is:

{
    "name": "door",
    "polygons": [
      {
        "points": [
          {
            "x": 0.12079093470323,
            "y": 0.16636921918746
          },
          ...
        ]
      }
    ]
}

HTTP Request

GET https://camio.com/api/users/:user/cameras/:camera/zones/:zone

URL Parameters

Name	Description	Details
user	The email address of the account owner or me for the signed-in user.	String, required, example: jane@example.com
camera	The name of the camera.	string, required, example: front
zone	The name of the zone.	string, required, example: door

Create or Edit Zone

The JSON request body is:

{
    "name": "door",
    "polygons": [
      {
        "points": [
          {
            "x": 0.12079093470323,
            "y": 0.16636921918746
          },
          ...
        ]
      }
    ]
}

HTTP Request

POST https://camio.com/api/users/:user/cameras/:camera/zones/:zone

URL Parameters

Name	Description	Details
user	The email address of the account owner or me for the signed-in user.	String, required, example: jane@example.com
camera	The name of the camera.	string, required, example: front
zone	The name of the zone.	string, required, example: door

Delete Zone

The response is:

204 (No Content)

HTTP Request

DELETE https://camio.com/api/users/:user/cameras/:camera/zones/:zone

URL Parameters

Name	Description	Details
user	The email address of the account owner or me for the signed-in user.	String, required, example: jane@example.com
camera	The name of the camera.	string, required, example: front
zone	The name of the zone.	string, required, example: door

Faces

Camio assigns face hashes to each face detected in each Event when face recognition is enabled. However, those face hashes aren’t user-friendly query terms. So to enable someone to search for “John” across all cameras with the simple query “john”, you must first assign labels to one or more face hashes that identify John.

Use this API endpoint to associate user-friendly labels with John’s face hash so that Camio knows that “_f-7102301d0904943d9131a146fb847c1ff28ea091” is “John”.

List all Face labels

The curl command is:

curl \
    -H "Authorization: token xyzauthtoken" \
    https://camio.com/api/faces/labels

The JSON response is 200:

{
    "labels": {
        "_f-7102301d0904943d9131a146fb847c1ff28ea091": [
            {
                "date_labeled": "2018-04-15T03:22:26.963-0000",
                "label": "John"
            }
        ],
        "_f-7102301d0904943d9131a146fb847c1ff28ea092": [
            {
                "date_labeled": "2018-04-15T03:22:26.963-0000",
                "label": "John"
            }
        ],
        "_f-7102301d0904943d9131a146fb847c1ff28ea093": [
            {
                "date_labeled": "2018-04-15T03:22:26.963-0000",
                "label": "Carter"
            }
        ],
        "_f-7102301d0904943d9131a146fb847c1ff28ea095": [
            {
                "label": "Some Guy"
            },
            {
                "label": "Suspect 1"
            }
        ]
    }
}

Retrieve a list of all of the face labels in the user’s account.

HTTP Request

GET https://camio.com/api/faces/labels

URL Parameters

Name	Description	Details
user	The email address of the account owner.	string, optional, example: jane@acme.com

Create a Face label

The curl command is:

curl \
    -H "Content-Type: application/json" \
    -H "Authorization: token xyzauthtoken" \
    -d '{"labels": {"_f-7102301d0904943d9131a146fb847c1ff28ea091": [{"label": "John"}]}}' \
    -X PUT https://camio.com/api/faces/labels

The JSON response is 200:

{
    "labels": {
        "_f-7102301d0904943d9131a146fb847c1ff28ea091": [
            {
                "date_labeled": "2018-04-15T18:27:30.040-0000",
                "label": "John"
            }
        ]
    }
}

HTTP Request

PUT https://camio.com/api/faces/labels

URL Parameters

Name	Description	Details
user	The email address of the account owner.	string, optional, example: jane@acme.com

Delete a Face label

The curl command is:

curl \
    -H "Content-Type: application/json" \
    -H "Authorization: token xyzauthtoken" \
    -d '{"labels": {"_f-7102301d0904943d9131a146fb847c1ff28ea091": []}}' \
    -X PUT https://camio.com/api/faces/labels

The JSON response is 200:

{
    "labels": {}
}

PUT an empty list of labels to delete the label(s) associated with a particular face hash.

HTTP Request

PUT https://camio.com/api/faces/labels

URL Parameters

Name	Description	Details
user	The email address of the account owner.	string, optional, example: jane@acme.com

Delete all Face labels

The curl command is:

curl \
    -H "Content-Type: application/json" \
    -H "Authorization: token xyzauthtoken" \
    -X DELETE https://camio.com/api/faces/labels

The response is:

204 (No Content)

This removes all face labels from the entire account.

HTTP Request

DELETE https://camio.com/api/faces/labels

URL Parameters

Name	Description	Details
user	The email address of the account owner.	string, optional, example: jane@acme.com

Hooks

Hooks enable services to be notified of events observed by Camio to take action on them.

For example, you may want to text the on-duty security guard whenever a person approaches a side alley between 2am and 5am, or you may want to perform additional image analysis whenever there are people detected in an event.

Hook Types

Type	Description
query_match	an event matches the hook’s query.
power_disconnected	a camera loses its A/C power connection.
job_completed	a Job has completed execution.

List all Hooks

The curl command is:

curl \
    -H "Authorization: token xyzauthtoken" \
    https://camio.com/api/users/test%40example.com/hooks?type=query_match

The JSON response is:

[
  {
    "id": "1",
    "type": "query_match",
    "callback_url": "https://example.com/camio/delivery",
    "callback_payload_type": "notification",
    "query": "front people in blue approaching mailbox"
  },
  {
    "id": "2",
    "type": "query_match",
    "callback_url": "https://example.com/camio/dog-walker",
    "callback_payload_type": "notification",
    "query": "people approaching dogbed"
  }
]

HTTP Request

GET https://camio.com/api/users/:user/hooks?type=:type

URL Parameters

Name	Description	Details
user	The email address of the account owner or me for the currently signed-in user. Guests require “Can Manage” permission.	string, required, example: test@example.com

Query String Parameters

Name	Description	Details
type	The Hook type.	string, required, example: query_match

Get Specific Hook

The curl command is:

curl \
    -H "Authorization: token xyzauthtoken" \
    https://camio.com/api/users/test%40example.com/hooks/1

The JSON response is:

{
  "id": "1",
  "type": "query_match",  
  "callback_url": "https://example.com/camio/delivery",
  "callback_payload_type": "notification",
  "query": "people in blue approaching mailbox"
}

HTTP Request

GET https://camio.com/api/users/:user/hooks/:hook

URL Parameters

Name	Description	Details
user	The URI encoded email address of the account owner or me for the currently signed-in user. Guests require “Can Manage” permission.	string, required, example: test%40example.com
hook	The id of the Hook	string, required, example: 1

Create Hook

The curl command is:

curl \
    -H "Content-Type: application/json" \
    -H "Authorization: token xyzauthtoken" \
    -d '{"callback_url": "http://example.com/camio/package-delivery", "type": "query_match", "query": "people in blue approaching mailbox at front gate", "callback_payload_type": "notification"}' \
    -X POST https://camio.com/api/users/me/hooks

The JSON response is:

{
  "id": "1",
  "type": "query_match",
  "callback_url": "https://example.com/camio/package-delivery",
  "callback_payload_type": "notification",
  "query": "people in blude approaching mailbox at front gate",
}

The command on the right creates a new hook requesting that:

• when the camera front or gate sees important motion, and
• the event is labeled people blue approaching mailbox, then
• execute HTTP POST http://example.com/camio/package-delivery
• sending the payload of images, video and metadata asociated with the callback_payload_type notification.

The json payload in the POST to the callback_url describes the event that triggered the Hook and includes the requested type of payload content.

HTTP Request

POST https://camio.com/api/users/:user/hooks

URL Parameters

Name	Description	Details
user	The email address of the account owner or me for the currently signed-in user. Guests require “Can Manage” permission.	string, required, example: test@example.com

Body

Name	Description	Details
client_metadata	Arbitrary json metadata that will be included in the payload sent to the callback_url.	string, optional, example: {"user_id":"xyz"}
config	The service level specification, including retry_parameters. See config.	object, optional, example: {"retry_parameters": {"min_backoff_seconds": 10,"task_retry_limit": 2}.
callback_url	The URL that receives the POST to process the callback payload	string, required, example: https://example.com/camio/package-delivery
callback_payload_type	The type of content included in the payload that’s sent to the callback_url. See callback_payload_type	string, required, analysis or notification.
mode	The optional mode for display convenience (unused currently).	string, optional, example: test
parsed_query	The exact conditional expression that filters which Events trigger the hook callback. See parsed_query conditions below.	string, optional, example: “camera == ‘front’ and (‘_color_blue’ in labels and ‘_ml_human’ in labels and ‘mailbox’ in labels and ‘gate’ in labels)”
query	The query text (as you’d enter it into the Camio search box) whose conditions must be matched in order to trigger the hook callback.	string, required unless parsed_query was specified, example: “people in blue approaching mailbox at front gate”
type	The event type that triggers the hook’s callback.	string, required, example: query_match

Hook Callback Payload Types

The payload sent to the callback_url is determined by the value of callback_payload_type.

Type	Description
analysis	include representative snapshot images, video and metadata to be used in further image analysis of the event.
notification	include metadata that describes the event sufficiently for notifications to people, apps and services.

Hook Config

Hook creation payload example that specifies config:

{
    "callback_payload_type": "analysis",
    "callback_url": "https://prod.example.com/callback",
    "config": {
        "retry_parameters": {
            "min_backoff_seconds": 10,
            "task_retry_limit": 3
        }
    },
    "mode": "production",
    "query": "vehicles approaching garage",
    "type": "query_match"
}

The response on success is 200. If task_retry_limit > 3, then response is 400 BAD REQUEST.

When config is omitted, the Hook is assumed to use the production default retry settings:

{ “callback_url”: “https://prod.example.com/callbacks”, “config”: { “retry_parameters”: { “min_backoff_seconds”: 10, “task_retry_limit”: 3 } } … }

Field	Description
min_backoff_seconds	The minimum number of seconds to wait before retrying the callback task.
task_retry_limit	The maximum number to retries after the initial failure of a callback. Currently, only values of 3 or lower are supported.

Hook Modes

mode is currently unused and informational only for viewing /hooks.

Type	Description
production	This is the default when no mode is specified.
test	Integration and unit testing.
development	Coding.

parsed_query conditions

It’s easier to supply query as the same text that you type into the search box. However, you can supply parsed_query instead if you want precise control over the interpretation without regard to the current state of the user’s account. For example, the parsing of the word garage in the query below is only known to be the name of camera when there is in fact a camera named “garage” in the user’s account. So in rare cases, when you want to create the Hook prior to the existence of a camera or zone defined by the user, then you can use parsed_query instead.

The parsed_query specifies the conditions of the filter and allows this subset of the Python conditional operators: and, or, not, in, <, <=, >, >=, ==, !=. The variables that can be referenced in the conditions include:

Variable	Description
camera	the name of the camera uploading the event
labels	a list of labels already associated with the event
date	the event start date as a python datetime object (date.year, date.day, etc are allowed).

For example, the query:

front and garage red or blue cars approaching

translates to the parsed_query:

(camera == "front" or camera == "garage") and (("_ml_approaching" in labels) and ("_ml_car" in labels) and ("_color_red" in labels or "_color_blue" in labels))

For “callback_payload_type” of “notification”, the JSON payload sent to the “callback_url” is:

{
  "hook_id": "1",
  "event": {
    "id": "abcdefghijklmnop",
    "source": "front",
    "earliest_date":"2015-05-21T02:07:44.636-0000",
    "latest_date":"2015-05-21T02:08:12.776-0000",
    "labels": ["mailbox", "_color_blue"]
  }
}

For “callback_payload_type” of “analysis”, the JSON payload sent to the “callback_url” is:

{
  "videos": [
    {
      "url": "https://storage.googleapis.com/camio_test/mv-109010...20-00166CF67F20.0_2017-07-07T20:27:57.355590_c75f3cb5-efd0-4bc4-87a0.mp4?Expires=1499462311&GoogleAccessId=397790679937%40developer.gserviceaccount.com&Signature=EtPRfbzP...FO%2BFeBk%3D", 
      "timestamp": {
        "meta_class": "datetime.datetime", 
        "date": "2017-07-07T20:27:57.355590"
      }, 
      "duration": 11.901999999999999, 
      "type": "video/mp4", 
      "id": "mv-109010...20-00166CF67F20.0_2017-07-07T20:27:57.355590_c75f3cb5-efd0-4bc4-87a0.mp4"
    }
  ], 
  "earliest_date": {
    "meta_class": "datetime.datetime", 
    "date": "2017-07-07T20:27:57.355590"
  }, 
  "labels": [], 
  "hook_id": "agxzfmNhbWlvLXRlc3RyEQsSBEhvb2s", 
  "images": [
    {
      "timestamp": "2017-07-07T20:28:03.306590", 
      "image_b64": "/9j/...Qf/2Q==", 
      "type": "image/jpeg", 
      "size": [
        376, 
        640
      ]
    }, 
    {
      "timestamp": "2017-07-07T20:27:59.339257", 
      "image_b64": "/9j/...//2Q==", 
      "type": "image/jpeg", 
      "size": [
        141, 
        240
      ]
    }, 
    {
      "timestamp": "2017-07-07T20:28:07.273923", 
      "image_b64": "/9j/...//Z", 
      "type": "image/jpeg", 
      "size": [
        141, 
        240
      ]
    }
  ], 
  "query": "1==1", 
  "latest_date": {
    "meta_class": "datetime.datetime", 
    "date": "2017-07-07T20:28:09.257590"
  }, 
  "user_id": "109010...20", 
  "event_id": "ev-109010...20-00166CF67F20.0_2017-07-07T20:28:18.440202_7d3721fe-5a06-47de-aa06.json", 
  "camera": "office_camera", 
  "aspect_ratio": 1.7021276595744681, 
  "callback_url": "https://camio.com/cam/hook/callback?certificate=FA5A313D1A572223E38...88B63C46EFA5D4235EAC927", 
  "client_metadata": null
}

Callback Payload

The json payload in the POST to the callback_url currently includes:

• the hook_id that you obtained when you created the hook.
• the event object that triggered the hook’s callback.
• the basic event attributes: id of the event, source (aka camera name), earliest_date, latest_date and labels.

For example, if the hook created in the example above were triggered only by an event from the front camera when observing a USPS worker in a blue uniform, then the POST payload would include all the labels that were required by the hook and the additional label blue as in the example on the right.

NOTE: Each url expires 60 minutes after an Event triggers the callback_payload_type of analysis. If your application requires more time to process the callback, then please contact us.

Delete Hook

The curl command is

curl \
    -H "Authorization: token yourOAuthToken" \
    -X DELETE https://camio.com/api/users/me/hooks/ag1zfmNhbWlvbG9nZ2VychELEgRIb29rGICA6MSIpaIJDA

The response is:

204 (No Content)

HTTP Request

DELETE https://camio.com/api/users/:user/hooks/:hook

URL Parameters

Name	Description	Details
user	The URI encoded email address of the account owner or me for the currently signed-in user. Guests require “Can Manage” permission.	string, required, example: test%40example.com
hook	The id of the hook.	string, required, example: 1

Get Hook Responses

The curl command is:

curl \
    -H "Authorization: token xyzauthtoken" \
    https://camio.com/api/users/me/hooks/1/responses

The JSON response looks like this:

[
    {
        "camera_name": "Front Entrance",
        "hook_id": "1",
        "id": "resp123",
        "full_response": {
            "labels": {
                "2018-01-06T23:48:10.485756": {
                    "tortilla": {
                        "polygon": [],
                        "probability": 0.10004174671723909
                    }
                },
                "2018-01-06T23:48:15.909222": {
                    "hippo": {
                        "polygon": [],
                        "probability": 0.7074233050120086
                    },
                    "monkey": {
                        "polygon": [],
                        "probability": 0.5078978427789357
                    },
                    "mouse": {
                        "polygon": [],
                        "probability": 0.7725894473848536
                    }
                },
                "2018-01-06T23:48:25.108267": {
                    "cat": {
                        "polygon": [],
                        "probability": 0.3008437942924863
                    },
                    "tortilla": {
                        "polygon": [],
                        "probability": 0.10477714044437214
                    }
                },
                "2018-01-06T23:48:27.662800": {},
                "2018-01-06T23:48:29.550933": {
                    "cat": {
                        "polygon": [],
                        "probability": 0.6073039910704522
                    },
                    "dog": {
                        "polygon": [],
                        "probability": 0.6687086411485385
                    },
                    "hippo": {
                        "polygon": [],
                        "probability": 0.5954041426842951
                    }
                }
            },
            "status": "success"
        },
        "user_id": "user123"
    }
]

This API endpoint is for developer debugging. Use it to verify the callback response received from your servers upon completion of an analysis Hook.

HTTP Request

GET https://camio.com/api/users/:user/hooks/:hook/responses

URL Parameters

Name	Description	Details
hook	The id of the Hook	string, required, example: 1
user	The URI encoded email address of the account owner or me for the currently signed-in user. Guests require “Can Manage” permission.	string, required.

Search

Search Video

An example request is:

curl \
    -H "Authorization: token abc123" \
    https://camio.com/api/search/?text=people+approaching+outdoor+walkway+7am+yesterday+in+sunglasses&num_results=50    

The JSON response is:

{
    "query": {
        "cameras": [
            "outdoor"
        ],
        "colors": [],
        "content_type": "image",
        "date": "2016-01-17T15:00:00.000-0000",
        "date_text_matched_lowercase": "7am yesterday",
        "earliest_date_considered": "2016-01-17T15:29:02.966-0000",
        "labels": [
            "_ml_approaching",
            "_ml_human",
            "walkway"
        ],
        "latest_date_considered": "2016-01-18T15:46:32.989-0000",
        "motion_type": "lmo",
        "object_type": "event",
        "remainder": "sunglasses",
        "sort": "asc",
        "text": "people approaching outdoor walkway 7am yesterday",
        "text_without_date_lowercase": "people approaching outdoor walkway",
        "user": "jcmaslan@gmail.com",
        "zones": [
            "walkway"
        ]
    },
    "result": {
        "bucket_type": "event",
        "buckets": [
            {
                "aspect_ratio": 1.3333334,
                "bucket_id": "ag1zfmNhbWlvbG9nZ2VyckYLEgVFdmVudCI7ZXY6MTE3NTUwMDAwNzk4Mzg2NzU3Njc3Om91dGRvb3I6MjAxNi0wMS0xN1QxNToyOTowMi45NjYwMDAM",
                "color": "#dadada",
                "count": 3,
                "cover_image_id": "ag1zfmNhbWlvbG9nZ2VychwLEg9VcGxvYWRlZENvbnRlbnQYgICw5If4nAkM",
                "croppings": {
                    "access_token": "AQBRUTiBpVZf2NUcxC52TTMedcAl",
                    "id": "eyJpZCI6Il"
                },
                "earliest_date": "2016-01-17T15:29:02.966-0000",
                "images": [
                    {
                        "content_type": "image/jpeg",
                        "date_created": "2016-01-17T15:29:02.966-0000",
                        "id": "ag1zfmNhbWlvbG9nZ2VychwLEg9VcGxvYWRlZENvbnRlbnQYgICw5POtgQgM",
                        "interest_level": 0,
                        "interest_score": 0.0,
                        "labels": [],
                        "source": "outdoor"
                    },
                    {
                        "content_type": "image/jpeg",
                        "date_created": "2016-01-17T15:29:03.836-0000",
                        "id": "ag1zfmNhbWlvbG9nZ2VychwLEg9VcGxvYWRlZENvbnRlbnQYgICwlKG_kwgM",
                        "interest_level": 0,
                        "interest_score": 0.0,
                        "labels": [],
                        "source": "outdoor"
                    },
                    {
                        "content_type": "image/jpeg",
                        "date_created": "2016-01-17T15:29:04.659-0000",
                        "id": "ag1zfmNhbWlvbG9nZ2VychwLEg9VcGxvYWRlZENvbnRlbnQYgICw5If4nAkM",
                        "interest_level": 0,
                        "interest_score": 0.0,
                        "labels": [],
                        "source": "outdoor"
                    }
                ],
                "labels": [
                    "_color_black",
                    "_ml_human",
                    "_ml_approaching",
                    "walkway"
                ],
                "latest_date": "2016-01-17T15:29:04.659-0000",
                "max_interest_level": 3,
                "source": "outdoor"
            },
            {
                "aspect_ratio": 1.3333334,
                "bucket_id": "ag1zfmNhbWlvbG9nZ2VyckYLEgVFdmVudCI7ZXY6MTE3NTUwMDAwNzk4Mzg2NzU3Njc3Om91dGRvb3I6MjAxNi0wMS0xN1QxNToyOToxOC4xNTEwMDAM",
                "color": "#dadada",
                "count": 5,
                "cover_image_id": "ag1zfmNhbWlvbG9nZ2VychwLEg9VcGxvYWRlZENvbnRlbnQYgICw5M-yoAgM",
                "earliest_date": "2016-01-17T15:29:18.151-0000",
                "images": [
                    {
                        "content_type": "image/jpeg",
                        "date_created": "2016-01-17T15:29:18.151-0000",
                        "id": "ag1zfmNhbWlvbG9nZ2VychwLEg9VcGxvYWRlZENvbnRlbnQYgICw5JuzjggM",
                        "interest_level": 0,
                        "interest_score": 0.0,
                        "labels": [],
                        "source": "outdoor"
                    },
                    {
                        "content_type": "image/jpeg",
                        "date_created": "2016-01-17T15:29:19.039-0000",
                        "id": "ag1zfmNhbWlvbG9nZ2VychwLEg9VcGxvYWRlZENvbnRlbnQYgICw5M-yoAgM",
                        "interest_level": 0,
                        "interest_score": 0.0,
                        "labels": [],
                        "source": "outdoor"
                    },
                    {
                        "content_type": "image/jpeg",
                        "date_created": "2016-01-17T15:29:19.783-0000",
                        "id": "ag1zfmNhbWlvbG9nZ2VychwLEg9VcGxvYWRlZENvbnRlbnQYgICwlPaxwAgM",
                        "interest_level": 0,
                        "interest_score": 0.0,
                        "labels": [],
                        "source": "outdoor"
                    }
                ],
                "labels": [
                    "_color_brown",
                    "_ml_mail",
                    "walkway",
                    "_color_black",
                    "_ml_human",
                    "_ml_approaching"
                ],
                "latest_date": "2016-01-17T15:29:19.783-0000",
                "max_interest_level": 3,
                "source": "outdoor",
                "videos": [
                    {
                        "content_type": "video/mp4",
                        "date_created": "2016-01-17T15:29:33.387-0000",
                        "id": "ag1zfmNhbWlvbG9nZ2VychwLEg9VcGxvYWRlZENvbnRlbnQYgICwpJXY0QkM",
                        "interest_level": 0,
                        "interest_score": 0.0,
                        "labels": [],
                        "source": "outdoor"
                    },
                    {
                        "content_type": "video/mp4",
                        "date_created": "2016-01-17T15:29:35.587-0000",
                        "id": "ag1zfmNhbWlvbG9nZ2VychwLEg9VcGxvYWRlZENvbnRlbnQYgICwpPvt3wkM",
                        "interest_level": 0,
                        "interest_score": 0.0,
                        "labels": [],
                        "source": "outdoor"
                    }
                ]
            }
        ],
        "count": 26,
        "earliest_date_considered": "2016-01-17T15:29:02.966-0000",
        "latest_date_considered": "2016-01-18T15:46:32.989-0000",
        "more_results": true
    }
}

Search recorded content with plain text queries. The query parser understands camera names, dates, zones, colors, direction of movement, and other object labels.

HTTP Request

GET https://camio.com/api/search

Query Parameters

The text parameter is the preferred way to search. Camio parses the text into a query object that is returned in the response.

For “paginated” searches, specify the date and sort query parameters to continue fetching earlier or later results. For example, a sequence of requests to fetch 300 results starting at 8am from your camera named “front” would look like this:

1. https://camio.com/api/search/?text=front+8am&num_results=100
2. https://camio.com/api/search/?text=front+8am&sort=asc&num_results=100&date=2017-05-17T08%3A24%3A40.828-0700
3. https://camio.com/api/search/?text=front+8am&sort=asc&num_results=100&date=2017-05-18T12%3A15%3A07.546-0700

In the example above, the date value for requests #2 and #3 is 1 millisecond later than the latest_date_considered found in the prior request’s result.

Name	Description	Details
text	The query text that will be parsed to populate the Query object. Dates can be expressed in natural language or as precise ISO8601 strings. Use the v: operator to search with a view_token (e.g. front 8am v:vxy5q2).	string, optional, example: people 6am to 8am
num_results	The number of results to return.	int, optional, default: 10, max: 100
date	Filter date in ISO8601 format.	string, optional, example: 2014-03-13T11:27:40.929-0000
sort	Either asc or desc for date ascending or date descending order	string, optional

Dates in query text

Camio interprets dates using Natural Language Processing and the current timezone of your browser. So here are examples of using dates and date ranges in the text parameter of an /api/search request assuming that you’re searching from Silicon Valley (Pacific Daylight Time) on May 17th, 2017:

text	date values
8am to noon	means earliest_date_allowed of 2017-05-17T15:00:00.000-0000 and latest_date_allowed of 2017-05-17T19:00:00.000-0000.
3 days ago at 3:30pm	means date of 2017-05-14T22:30:00.000-0000.
Monday 2pm EDT	means date of 2017-05-14T18:00:00.000-0000.

Colors in query text

The query parser currently matches only these colors: red, pink, brown, orange, yellow, green, cyan, blue, purple, magenta, white, gray, black

Directions of movement in query text

The query parser currently understands only two directions of movement: approaching, departing

Response JSON

The result is the important part of the response. However, the parsed query object is also included for future versions of /api/search and is derived from having parsed the text parameter of the request.

result

Name	Description	Details
bucket_type	The type event is a video event of variable length up to 60 seconds long	string
bucket_id	This is the event_id when bucket_type is event. This id is used only for interactions.	string
color	The average color of the event to be used as placeholder until thumbnails have been fetched	string, optional
count	The number of results	integer
earliest_date	The earliest date contained in the bucket	ISO8601 date string
latest_date	The latest date contained in the bucket	ISO8601 date string
source	The camera name of the video source	string, required
labels	The indexed labels that describe color, direction of movement, objects, OCR text, etc…	List of string
earliest_date_considered	The earliest date examined by the server when searching	ISO8601 date string
latest_date_considered	The latest date examined by the server when searching	ISO8601 date string
more_results	false when the server is certain that there are no more results that will match the query
by trying an earlier date for a desc query or a later date for an asc query.	boolean, required

query

Name	Description	Details
start_date	The earliest date inclusive in ISO8601 format.	string, optional, example: 2014-03-13T11:27:40.929-0000
end_date	The latest date date inclusive ISO8601 format.	string, optional, example: 2014-03-13T11:32:01.134-0000
events	List of string Event ids to fetch.	List. optional, used only for fetching an enumerated list of Events.
remainder	The portion of the input Query.text that was unmatched by the parser.	string, optional. For example, the query [backyard purple bucket] may have a Query.remainder of bucket if Camio’s query parser couldn’t match the word bucket with any object, camera, color, zone, label, direction of movement, etc…
cameras	The list of camera matches that the parser found in the input text.	List, optional.
zones	The list of zone matches that the parser found in the input text.	List, optional.
colors	The list of color matches that the parser found in the input text.	List, optional.
date_text_matched_lowercase	The portion of the input text that was used to determine the date expression in the query.	string, optional. For example the Query.text people approaching entrance last Friday 2pm would have Query.date_text_matched_lowercase last friday 2pm.
text_without_date_lowercase	This value is just for the convenience of the call in avoiding the need to subtract the matched date text from the Query.text	string, optional.
parsed_query	The conditional expression derived from having parsed the input text.	string.

ID of images and videos

The id of images and videos in search results is unique to the particular search result. The id serves as a bearer token that grants permission to view the content. Though the id is long-lived currently, do not rely on the id as a permanent identifier. To fetch the actual video or image, use the camera name and the id in a request to get the content. For example, to fetch the video having the id of eyJ0IjoiQVFDbmxu from the camera named west, the request is:

https://camio.com/api/users/me/cameras/west/content/eyJ0IjoiQVFDbmxu

The response is a 302 redirect to an URL that expires in 30 minutes that looks something like this:

https://storage.googleapis.com/camio/mv-1175XXXX677-00E04CC27CC8.0_2018-08-23T00:00:43_7dbab387-6d17-4ec0-ae7f-b13c1048d276.mp4?GoogleAccessId=686269513085@developer.gserviceaccount.com&Expires=1535002523&Signature=MtunhlREDACTEDN36DnU

Search Cameras

An example request is:

curl \
    -H "Authorization: token abc123" \
    https://camio.com/api/search/cameras?text=work

The JSON response is:

{
    "query": {
        "cameras": [
            "east",
            "Office",
            "west"
        ],
        "object_type": "camera",
        "parsed_query": "camera == \"east\" or camera == \"Office\" or camera == \"west\"",
        "remainder": "",
        "sort": "desc",
        "text": "work",
        "text_without_date_lowercase": "work",
        "user": "test@example.com",
        "view_tokens_text_matched": [],
    },
    "result": {
        "bucket_type": "camera",
        "buckets": [
            {
                "bucket_id": "user123456:00E04CC27CC5:00E04CC27CC5.0",
                "labels": [
                    "California",
                    "San Mateo",
                    "Work",
                    "94401"
                ],
                "location": {
                    "accuracy": 1.0,
                    "location": {
                        "lat": 37.5669694,
                        "lng": -122.32645530000002
                    }
                },
                "source": "east"
            },
            {
                "bucket_id": "user123456:00166CF67F20:00166CF67F20.0",
                "labels": [
                    "California",
                    "San Mateo",
                    "Work",
                    "94401"
                ],
                "location": {
                    "accuracy": 1.0,
                    "location": {
                        "lat": 37.5669694,
                        "lng": -122.32645530000002
                    }
                },
                "source": "Office"
            },
            {
                "bucket_id": "user123456:00E04CC27CC8:00E04CC27CC8.0",
                "labels": [
                    "California",
                    "San Mateo",
                    "Work",
                    "94401"
                ],
                "location": {
                    "accuracy": 1.0,
                    "location": {
                        "lat": 37.5669694,
                        "lng": -122.32645530000002
                    }
                },
                "source": "west"
            }
        ]
    }
}

Search for cameras that match the argument text query. All query terms unrelated to camera names or camera labels are currently ignored. That is, the search is simply finding cameras that have a particular name or label associated with them.

HTTP Request

GET https://camio.com/api/search/cameras

URL Parameters

Name	Description	Details
text	The query text that will be parsed to populate the Query object. Use the v: operator to search with a view_token (e.g. mexico v:vxy5q2).	string, optional, example: work or home
num_results	The number of results to return.	int, optional, default: 10, max: 100

Content

Get Content (authenticated)

curl command is:

curl \
    -H "Authorization: token xyzauthtoken" \
    https://camio.com/api/users/me/cameras/Office/content/eyJ...OiJjYW1pbyJ9fQ

A specific content item (image or video) can be retrieved by its ID that is returned in the search response.

HTTP Request

GET https://camio.com/api/users/me/cameras/:camera/content/:id

URL Parameters

Name	Description	Details
camera	The name of the camera.	string, required, example: front
id	The id of the content	string, required

Get Content (with access_token)

The curl command is:

curl \
    -H "Content-Type: application/json" \
    -d '[{"id":"eyJsIjp7ImM...XMifX0", "access_token":"AQCahb56...TV0zm4TJ9pmrU4"}]' \
    -X POST https://camio.com/api/content/?resize=true&w=200&h=200

The JSON payload for the POST is a list of objects with only id and ‘access_token’:

[
  {
    "id":"eyJsIjp7ImM...XMifX0",
    "access_token":"AQCahb56...TV0zm4TJ9pmrU4"
  }
]

Get one or more content items (images or video) using a list of ids and access_tokens. POST is used so that the caller can supply a json list in the payload of the request.

HTTP Request

POST https://camio.com/api/content

URL Parameters

Name	Description	Details
w	The width (in pixels) of the bounding box to resize the image to fit within. Only used if thumbnails are being fetched.	int, optional, default: 150
h	The height (in pixels) of the bounding box to resize the image to fit within. Only used if thumbnails are being fetched.	int, optional, default: 112
quality	The quality of the jpeg image compression.	int, optional, min: 1, max: 100, default: 85
resize	true to resize	optional, true or false, default: false

JSON Payload

When requesting the content referenced in a search result of a Camio, you can supply a list of mappings between an id and access_token to authorized access to the content.

Name	Description	Details
id	The id of the content	string, required
access_token	The access_token supplied in the result of a prior search that used view_tokens to authorize the search.	string, required

Get Croppings Content

The curl command is:

curl \
    -H "Content-Type: application/json" \
    -d '{"id":"eyJsIjp7ImM...XMifX0", "access_token":"AQCahb56...TV0zm4TJ9pmrU4"}' \
    -X POST https://camio.com/api/content/croppings

The JSON payload for the POST is a single object specifying the id and ‘access_token’:

{
    "id":"eyJsIjp7ImM...XMifX0",
    "access_token":"AQCahb56...TV0zm4TJ9pmrU4"
}

The response JSON is an object that includes the list of croppings, only some of which have image.data:

{
  "croppings": [
    {
      "flow_idx": 0, 
      "area": 194.0, 
      "timestamp": {
        "meta_class": "datetime.datetime", 
        "date": "2018-03-19T04:39:27.973273"
      }, 
      "image": {
        "meta_class": "JPEGimage", 
        "data": "/9j/4AAQSkZ**REDACTED IMAGE DATA****/2Q=="
      }, 
      "labels": {
        "meta_class": "set", 
        "set": [
          "_color_black"
        ]
      }, 
      "shape": [
        226, 
        303
      ], 
      "region_bbox": [
        [
          21.0, 
          26.0
        ], 
        [
          43.0, 
          39.0
        ]
      ], 
      "frame_idx": [
        "00E04CC27CC5.0_2018-03-19T04:39:21_213e37ab-73a9-4570-8169-7fa9087b8af6.mp4", 
        49
      ]
    }, 
    {
      "flow_idx": 0, 
      "area": 155.0, 
      "timestamp": {
        "meta_class": "datetime.datetime", 
        "date": "2018-03-19T04:39:27.261714"
      }, 
      "image": null, 
      "labels": {
        "meta_class": "set", 
        "set": [
          "_color_black", 
          "_color_gray"
        ]
      }, 
      "shape": [
        330, 
        415
      ], 
      "region_bbox": [
        [
          15.0, 
          20.0
        ], 
        [
          44.0, 
          39.0
        ]
      ], 
      "frame_idx": [
        "00E04CC27CC5.0_2018-03-19T04:39:21_213e37ab-73a9-4570-8169-7fa9087b8af6.mp4", 
        44
      ]
    }
  ], 
  "local_camera_id": "00E04CC27CC5.0"
}

Get the list of cropped motion regions of an Event. Only some of the croppings in the response will have image.data, since not all high resolution images are uploaded to the cloud.

POST is used in anticipation of supporting multiple requests in a single command later.

HTTP Request

POST https://camio.com/api/content/croppings

URL Parameters

The id and the access_token are obtained from the croppings object in the Search response.

Name	Description	Details
id	The id of the content	string, required
access_token	The access_token supplied in the result of a prior search that used view_tokens to authorize the search.	string, required

Get Latest Live Image

Example request is:

curl \
    -H "Authorization: token xyzauthtoken" \
    https://camio.com/api/content/live/west?user=sarah%40example.com&autoon=true

Response is the Base64 encoded jpeg image as JSON:

{
    "camera": "west",
    "image_bytes": "/9j//gAQTMQ1M9***REDACTED***",
    "image_date": "2018-08-14T01:21:50.636-0000",
    "is_online": true,
    "refresh_required": false
}

Get the latest available live image from a specific camera.

HTTP Request

GET https://camio.com/api/content/live/:camera/

URL Parameters

Name	Description	Details
camera	The name of the camera to fetch the lastest image from.	string, required, example: front

Query Parameters

Name	Description	Details
user	The email address of the owner of the camera. If the camera is owned by the current user this can be omitted.	string, optional, example: test@example.com
quality	The quality of the jpeg image compression.	int, optional, min: 1, max: 100, default: 85
view_tokens	The comma-separated list of view_tokens associated with Camio(s) that were shared without any end date (so that they extend to all FUTURE dates and are therefore permitted to server the latest live images.	string, optional, example: 41cmi5mh66m8
output	The output content type desired.	string, optional, example: jpeg. When omitted, the default is json.
w	The width (in pixels) of the bounding box to resize the image to fit within.	int, optional, example 320. Default is full width.
h	The height (in pixels) of the bounding box to resize the image to fit within.	int, optional, example 180. Default is full height.
autoon	Set this value to true to force Camio to request fast frame uploads of the latest live snapshot image.	boolean, optional. Default is false.

As an example of a public link that requires no OAuth Authorization header because of its use of the view_tokens query parameter, this is the latest live image from mailbox area of the Camio office, resized to a small thumbnail 320x180:

https://camio.com/api/content/live/east?view_tokens=41cmi5mh66m8&output=jpeg&w=320&h=180

To create a view_token for the latest live image of a single camera, see this help article. To create the view_token programatically with this API, create a Camio with a query object with only one camera in cameras, start_date without an end_date, and sort of asc.

Upload Content

The following cURL command uploads an MP4 via the Camio Box API:

curl -H "Content-Type:video/mp4" \
    -X POST \
    -T "filename.mp4" \
    "https://192.168.1.57/box/content/?camera_id=cam123&local_camera_id=local456&hash=abcdefghijk&timestamp=2017-04-22T13:44:12.0000"

Uploading video via Camio Box is the preferred method because of the bandwidth, precision, cost and quality benefits of analyzing video on your local network before sending anything to the cloud.

You POST video to the Camio Box /box/content endpoint with Query Parameters that associate the video with a registered camera. The video is segmented, analyzed, and labeled by the Camio pipeline. The indexed results are then accessible via the Search API or via the Camio webapp.

HTTP Request

POST https://192.168.1.57/box/content

URL Parameters

None. However you must obtain the ip_address of your Camio Box, which can be found on the camio.com/boxes page.

Query Parameters

TODO(carter) change accesstoken -> access_token

Name	Description	Details
accesstoken	device_id of the Camio Box recieving the content	string, required
local_camera_id	the local_camera_id that was assigned to the camera by the user at the time of creating the camera	string, required
camera_id	the camera_id that was returned by camio.com at the time of creating the camera	string, required
hash	SHA sum of the content being posted, used to map segments back to the original source video	string, required
timestamp	the starting timestamp of the video in ISO8601 format YYYY-mm-ddTHH:MM:SS.FFFF	string, required, example: 2014-07-21T20:38:32.183

Body

• H.264 encoded video content in an mp4 container.

Upload Content (Cloud)

The following cURL command uploads an MP4:

curl -H "Content-Type:video/mp4" \
    -X POST \
    -T "filename.mp4" \
    "https://camio.com/api/users/abc123pdq/cameras/front/content/?camera_id=1234&upload_mode=video"

The following cURL command will upload a JPEG image:

curl -H "Content-Type:image/jpeg" \
    -X POST \
    -T "2014-07-21T20:38:32.183-07:00.jpeg" \
    "https://camio.com/api/users/51r6kndapc/cameras/front/content/2014-07-21T20:38:32.183-07:00.jpeg?camera_id=1234"

NOTE: The preferred method of uploading Content is via the Camio Box /box/content API. This cloud method of uploading is DEPRECATED.

Content can be uploaded to Camio via both POST and PUT. If the :name part of the url or filename part of a multi-part attachment specifies a parseable timestamp, then Camio will honor that timestamp if you include in options the value parse_timestamp.

HTTP Request

POST https://camio.com/api/users/me/cameras/:camera/content/:name

or

PUT https://camio.com/api/users/me/cameras/:camera/content/:name

URL Parameters

Name	Description	Details
camera	The name of the camera.	string, required, example: front
name	An optional filename. If the filename includes a timestamp, it will be used to help synchronize sequences.	string, optional, example: 2014-07-21T20:38:32.183-07:00.jpeg

Query Parameters

Name	Description	Details
camera_id	The id of the camera. Any string that is unique among all the cameras belonging to the account is OK. It’s nice to use something reliably unique regardless of the owning account - such as the camera’s mac address - but you can create your own simpler id as well (e.g. cam123).	string, required, example: 40523085002820672672296
upload_mode	Indicates the type of content the camera uploads as the basis for Event creation. Set to video if the camera uploads only video as the basis for creating Events; otherwise, the uploaded video will be treated only as a secondary “backing” for Events created by image snapshots.	string, optional, accepts: image, video, default: image
img_type	The type of image (or video) being uploaded. Values include m for motion triggered, a for audio triggered, h for heartbeat uploads, and v for live snapshots.	string, optional, default: m
rotation	The degrees rotation required for the video to play in its correct orientation.	string, optional, accepts: 0, 90, 180, 270, default: 0
video_length	The length of the video in seconds as a floating point. Without supplying this value, the video length is calculated server-side with less precision	string, optional, accepts numeric values > 0.0 like 20.18
options	CSV string list of special processing options. Values include alternate when uploading alternate media of another resolution or encoding in support of an existing Event, no_analysis to accept uploaded video as-is as its own Event, without image analysis or machine learning, and parse_timestamp to infer timestamp of content from natural language processing of the uploaded filename.	string, optional, accepts: alternate, no_analysis, parse_timestamp

Sample request is:

https://camio.com/api/users/me/cameras/Office/content/2016-01-19T00%3A59%3A09.119-0000.webm?camera_id=ccw0259026XYZ&video_length=6.452

The JSON response is:

{
    "camera": "Office",
    "camera_id": "ccw0259026XYZ",
    "content_type": "video/webm",
    "date_created": "2016-01-19T00:59:18.193-0000",
    "date_received": "2016-01-19T00:59:18.193-0000",
    "id": "ag1zfmNhbWlvbG9nZ2VychwLEg9VcGxvYWRlZENvbnRlbnQYgICw1NLtmwoM",
    "interest_hash": 0,
    "interest_score": 0.0,
    "ip_address": "73.170.185.225",
    "is_metadata_set": true,
    "labels": [],
    "name": "2016-01-19T00:59:09.119-0000.webm",
    "platform": "web",
    "size": 796042,
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.106 Safari/537.36",
    "user_email": "test@example.com",
    "user_id": "11712X1",
    "video_length": 6.452
}

JSON Response

The JSON response echos the values supplied in the request and adds metadata derived from the request. The added metadata is described below.

Name	Description	Details
date_created	The timestamp treated as the actual time of the Event in real life.	If you’ve included &options=parse_timestamp in your request, then this value is determined by the parsing of the timestamp you supplied.
date_received	The timestamp at which the content reached camio.com servers.	This is the same as the date_created if you didn’t request &options=parse_timestamp.
id	The unique id associated with this piece of content.
name	The filename as derived from either the url or the filename in the multi-part attachment.
ip_address	The IP address of the origin of the request.
size	The size in bytes of the content uploaded.
user_agent	The User-Agent from the request header.
user_email	The email address of the owner of the account receiving the content.
user_id	The unique id of the owner of the account receiving the content.

Jobs

A Job tracks the completion of a long-running batch import operation.

Each Job has one or more Shards, and each Shard receives a JSON payload from the client that describes the SHA hash of the video file and its correlation to the original filename. That way, a mapper can subsequently check the completion status of the asynchronous labeling of all the video events associated with the input video file.

List all Jobs

An example request is:

curl \
    -H "Authorization: token oauth123xyz" \
    https://camio.com//api/jobs

The JSON response is:

[
    {
        "job_id": "agpIDYggsM",
        "request": {
            "device_id": "d123pdq",
            "item_count": 4099, 
            "item_average_size_bytes": 512, 
            "cameras":[
                {"name": "starboard"}
            ],
            "earliest_date":"2017-04-30T05:17:22.551-0700", 
            "latest_date": "2017-05-17T16:35:36.362-0700"
        },
        "shard_map": {
            "0": {
                "item_count": 2048,
                "job_id": "agpIDYggsM",
                "shard_id": "0",
                "status": "missing"
            },
            "1": {
                "item_count": 2048,
                "job_id": "agpIDYggsM",
                "shard_id": "1",
                "status": "missing"
            },
            "2": {
                "item_count": 3,
                "job_id": "agpIDYggsM",
                "shard_id": "2",
                "status": "missing"
            }
        },
        "status": "shards_missing"
    }
]

This lists all Jobs that were created by the current user. This command fetches the status of each Job with each call.

Job Status

The Job status values are:

Value	Description
shards_missing	One or more of the Job’s shards haven’t yet been uploaded via the PUT :upload_url.
running	All shards have been uploaded and the Job is running.
completed	All shards of the Job have been labeled, so the Job is complete.

Job Shard Status

The Job Shard status values are:

Value	Description
missing	The Shard hasn’t been uploaded via the PUT :upload_url.
running	The Shard has been uploaded and is being labeled.
completed	The Shard has been labeled.

HTTP Request

GET https://camio.com/api/jobs

Get Specific Job

An example request is:

curl \
    -H "Authorization: token oauth123xyz" \
    https://camio.com//api/jobs/agpIDYggsM

The JSON response is:

{
    "job_id": "agpIDYggsM",
    "request": {
        "device_id": "d123pdq",
        "item_count": 4099, 
        "item_average_size_bytes": 512, 
        "cameras":[
            {"name": "starboard"}
        ],
        "earliest_date":"2017-04-30T05:17:22.551-0700", 
        "latest_date": "2017-05-17T16:35:36.362-0700"
    },    
    "shard_map": {
        "0": {
            "item_count": 2048,
            "job_id": "agpIDYggsM",
            "shard_id": "0",
            "status": "missing"
        },
        "1": {
            "item_count": 2048,
            "job_id": "agpIDYggsM",
            "shard_id": "1",
            "status": "missing"
        },
        "2": {
            "item_count": 3,
            "job_id": "agpIDYggsM",
            "shard_id": "2",
            "status": "missing"
        }
    },
    "status": "shards_missing"
}

HTTP Request

GET https://camio.com/api/jobs/:job_id

URL Parameters

Name	Description	Details
job_id	The job_id returned from the PUT /api/jobs	string, required.

See Job Status and Job Shard Status for the status values.

Create Job

An example request is:

curl \
    -H "Content-Type: application/json" \
    -H "Authorization: token xyzauthtoken" \
    -d '{item_count": 4099, "item_average_size_bytes": 512, cameras":[{"name": "starboard"}], "earliest_date":"2017-04-30T05:17:22.551-0700", "latest_date": "2017-05-17T16:35:36.362-0700", "device_id": "d123pdq"}' \
    -X POST https://camio.com/api/jobs

The JSON response is:

{
    "job_id": "agpIDYggsM",
    "request": {
        "device_id": "d123pdq",
        "item_count": 4099, 
        "item_average_size_bytes": 512, 
        "cameras":[
            {"name": "starboard"}
        ],
        "earliest_date": "2017-04-30T05:17:22.551-0700", 
        "latest_date": "2017-05-17T16:35:36.362-0700"
    },    
    "shard_map": {
        "0": {
            "item_count": 2048,
            "job_id": "agpIDYggsM",
            "shard_id": "0",
            "upload_url": "https://storage.googleapis.com/camio_test_mr_output/bij-agpIDYggsM-0?GoogleAccessId=397790679937@developer.gserviceaccount.com&Expires=1493001520&Signature=Jl4q%2FhXGTpNNRPWw6nQYnT0YxR%2BYHap38s1GmF0crKJIyW5p0YOb1BfECeG5mTd4HCWI0hi7I4ZVe2xwdOSgajvdOJPFEEm%2Fig%2F8xgwm6JQv8lq3CGVXJsJtKj9UervBnCJrr2dxE788RElTXCSljh5DfFBXDhDH09%2BQx8B5sWc%3D"
        },
        "1": {
            "item_count": 2048,
            "job_id": "agpIDYggsM",
            "shard_id": "1",
            "upload_url": "https://storage.googleapis.com/camio_test_mr_output/bij-agpIDYggsM-1?GoogleAccessId=397790679937@developer.gserviceaccount.com&Expires=1493001520&Signature=kXfCRwkDudTAiFCW%2BvXgTR%2Bv0r3QtBiIBI%2Bc%2FjhjspGen2ZbBem04NJ3rmMueCNddfeUvOkyC3sVkJ4J%2FGsdcrCyp8WxWmI9lclh0YWPHKUkFAfSIyGVdSuUBZbieLzcZXjROVeR2aWknM6NQUEyZKL15HcRzTjA8QWEUppI6tM%3D"
        },
        "2": {
            "item_count": 3,
            "job_id": "agpIDYggsM",
            "shard_id": "2",
            "upload_url": "https://storage.googleapis.com/camio_test_mr_output/bij-agpIDYggsM-2?GoogleAccessId=397790679937@developer.gserviceaccount.com&Expires=1493001520&Signature=L80gTRdfzFqEd7znyJ3qHQlTVRJaIWjXcA6G2RujCmDpALPW3CVoIfoVzOX2jwmq0Q%2BGM6IrMA664%2BH0%2FBRDNgE1NPtwT763cLutiwGAwUwnrLyP3WxF4Ysmdb5Da2syiiufe7amT4%2FpSbWAyn2b59cqNmK%2Fh0FUlAi7cW88gek%3D"
        }
    }
}

The command on the right creates a new Job with 4099 items, where each item is about 512 bytes in size. The server determines how many shards are required and responds with a shard_map keyed by shard_id with values that describe the item_count of each shard and the upload_url that will receive the payload describing that particular shard.

HTTP Request

PUT https://camio.com/api/jobs

Body

The JSON body is the job request described by these fields.

Name	Description	Details
item_count	The total count of all items in the Job.	integer, required.
item_average_size_bytes	The average size of each individual item in bytes. This is the size of only the filename + hash + any other metadata (NOT the size of the video itself)	integer, required.
device_id	Only if you want it for accounting, include the device_id of the Camio Box processing the job	String, optional.
cameras	The list of camera objects included in the job, and only the name field of the camera is required	List of cameras, only camera.name required.
earliest_date	The earliest date in the video submitted for this job	ISO8601 String, required. e.g. "2017-04-30T05:17:22.551-0700"
latest_date	The latest date in the video submitted for this job	ISO8601 String, required. e.g. "2017-05-17T16:35:36.362-0700"

Create Job Shard Hash Map

When you create a Job, the JSON response includes the signed upload_url to use for the PUT of the hash_map for each Shard of the Job. NOTE: the upload_url returned in the response is signed and valid only for a limited duration of time (e.g. 20 minutes), so it’s important that you upload all Shards of your Job immediately after creating the Job.

The key of the hash_map is the SHA hash of the input video file like this:

{
  "job_id": "agpIDYggsM",
  "shard_id": "0",
  "item_count": 2048,
  "hash_map":{
    "xyzpdq123": {"original_filename": "HiC2_20170324T120123000"},
    "xyzpdqABC": {"original_filename": "HiC2_20170324T120133000"}
  }
}

HTTP Request

PUT :upload_url

URL Parameters

Name	Description	Details
upload_url	The upload_url of the shard that was returned from PUT /api/jobs. The signed url expires, so you must perform this PUT within 20 minutes of creating the Job.	string, required.

An example Hook upon job_completed

curl \
    -H "Content-Type: application/json" \
    -H "Authorization: token xyzauthtoken" \
    -d '{"callback_url": "https://mycompany.com/job-completed", "type": "job_completed"}' \
    -X POST https://camio.com/api/users/me/hooks

The payload delivered to the callback_url for job_completed is:

{
  "job_id": "job123",
  "type": "job_completed",
}

To be notified upon completion of the job, create a Hook with the type job_completed as shown in the example on the right.

Your callback_url (https://mycompany.com/job-completed) for the Hook performs whatever post-labeling actions are required for your application (e.g. using /api/search to fetch the events with particlar labels).

Delete Job

An example request is:

curl \
    -H "Authorization: token xyzauthtoken" \
    -X DELETE \
    https://camio.com/api/jobs/agpIDYggsM

The response is:

204 (No Content)

Deleting a Job doesn’t stop the labeling that was already underway. So deleting a Job is really only usefule if you prefer to purge the history of Jobs indexed under your user_id.

HTTP Request

DELETE https://camio.com/api/jobs/:job_id

URL Parameters

Name	Description	Details
job_id	The id of the Job.	string, required.

Camios

A Camio is some portion of your content that can be shared via link without requiring viewers to sign-in. You define the subset of your content to share, then send a link that enables others to view the Camio without sign-in.

You can also restrict access to the link by adding specific collaborators, which can be either individual users (e.g. lisa@jones.com) or domains (acme.com).

List all Camios

An example request is:

curl "https://camio.com/api/users/me/camios" \
    -H "Authorization: token abc123"

The JSON response is:

[
    {
        "date_created": "2017-04-10T04:20:47.118-0000",
        "id": "agxyz123",
        "name": "Query link Liverpool 6:45pm EDT April 9 2017 to 11pm EDT April 9 2017 all",
        "owner": {
            "user_id": "user123456"
        },
        "query": {
            "cameras": [
                "Liverpool"
            ],
            "content_type": "image",
            "date": "2017-04-09T22:45:00.000-0000",
            "earliest_date_allowed": "2017-04-09T22:45:00.000-0000",
            "labels": [],
            "latest_date_allowed": "2017-04-10T03:00:00.000-0000",
            "user": "jcmaslan@gmail.com"
        },
        "type": "public",
        "view_token": "AQCCckxhtQEzx_G5rU_4iRym7awAqth9jQrKDSnAGBe0CJbpUi1tvXkiZs5gTaPF0Tt9fD_p27_9nPotu6oSBobt"
    },
    ...
]

HTTP Request

GET https://camio.com/api/users/me/camios

Get a Camio

An example request is:

curl "https://camio.com/api/users/me/camios?id=agxyz123" \
    -H "Authorization: token abc123"

The JSON response is:

    {
        "date_created": "2017-04-10T04:20:47.118-0000",
        "id": "agxyz123",
        "name": "Query link Liverpool 6:45pm EDT April 9 2017 to 11pm EDT April 9 2017 all",
        "owner": {
            "user_id": "user123456"
        },
        "query": {
            "cameras": [
                "Liverpool"
            ],
            "content_type": "image",
            "date": "2017-04-09T22:45:00.000-0000",
            "earliest_date_allowed": "2017-04-09T22:45:00.000-0000",
            "labels": [],
            "latest_date_allowed": "2017-04-10T03:00:00.000-0000",
            "user": "jcmaslan@gmail.com"
        },
        "type": "public",
        "view_token": "AQCCckxhtQEzx_G5rU_4iRym7awAqth9jQrKDSnAGBe0CJbpUi1tvXkiZs5gTaPF0Tt9fD_p27_9nPotu6oSBobt"
    }

HTTP Request

`GET https://camio.com/api/users/me/camios

URL Parameters

Name	Type	Description
id	string	Required. e.g. agxyz123

Create Camio

An example request is:

curl \
    -H "Content-Type: application/json" \
    -H "Authorization: token abc123" \
    -X PUT \
    -d '{"name": "Query link Liverpool 6:45pm to 11pm","query": {"text": "Liverpool 6:45pm EDT April 9 2017 to 11pm EDT April 9 2017 all jcmaslan@gmail.com"},"type": "public"}' \
    https://camio.com/api/users/me/camios

An example of the body of the JSON request is:

{
    "name": "Query link Liverpool 6:45pm to 11pm",
    "query": {
        "text": "Liverpool 6:45pm EDT April 9 2017 to 11pm EDT April 9 2017 all jcmaslan@gmail.com"
    },
    "type": "public"
}

The JSON respons is:

{
    "date_created": "2017-04-10T04:20:47.118-0000",
    "id": "agxyz123",
    "message": {
        "body": "See this #Camio https://camio.com/c/s1ui6ygpwveo/app via @camio",
        "subject": "See this Camio Query Link",
        "url": "https://camio.com/c/s1ui6ygpwveo/app"
    },
    "name": "Query Link Liverpool 6:45pm to 11pm",
    "owner": {
        "user_id": "user123456"
    },
    "query": {
        "cameras": [
            "Liverpool"
        ],
        "date": "2017-04-09T22:45:00.000-0000",
        "earliest_date_allowed": "2017-04-09T22:45:00.000-0000",
        "labels": [],
        "latest_date_allowed": "2017-04-10T03:00:00.000-0000",
        "motion_type": "all",
        "sort": "asc",
        "user": "jcmaslan@gmail.com",
    },
    "type": "public",
    "url": "https://camio.com/c/s1ui6ygpwveo/app",
    "view_token": "AQCCckxhtQEzx_G5rU_4iRym7awAqth9jQrKDSnAGBe0CJbpUi1tvXkiZs5gTaPF0Tt9fD_p27_9nPotu6oSBobt",
    "view_token_short": "s1ui6ygpwveo"
}

When enumerating Events instead, the input JSON is:

{
    "name": "My Camio",
    "query": {
        "events": ["IDXYZ", "IDABC", "IDDEF"]
    },
    "type":"public"
}

Specify the details of the camio as JSON in the POST body. The query input may specify either query.text or query.events. Learn more about Camio Query Links, but the most common sharing is via the enumerated event ids specified as a list in query.events.

HTTP Request

PUT https://camio.com/api/users/me/camios

Body

Name	Type	Description
name	string	Optional. Defaults to the query description.
query	Query	Query that defines the constraints on the Camio.
type	string	Optional. “public” or “private” - default is “public”.

Update a Camio

An example request is:

curl \
    -H "Content-Type: application/json" \
    -H "Authorization: token abc123" \
    -X POST \
    -d '{"id": "agxyz123", "collaborators":{...}' \
    https://camio.com/api/users/me/camios

An example of the body of the JSON request is:

{
    "id": "agxyz123",
    "collaborators": {
        "domains": {
            "camio.com": {
                "domain": "camio.com",
                "permissions": [
                    {
                        "role": "viewer"
                    }
                ]
            }
        },
        "users": {
            "john@gmail.com": {
                "permissions": [
                    {
                        "role": "viewer"
                    }
                ],
                "user": {
                    "email": "john@gmail.com"
                }
            },
            "sue@yahoo.com": {
                "permissions": [
                    {
                        "role": "viewer"
                    }
                ],
                "user": {
                    "email": "sue@yahoo.com"
                }
            }
        }
    }
}

NOTE: Currently, this API endpoint updates only the collaborators associated with an existing Camio to restrict use of the link to particular, authenticated users. Add or remove users and/or domains who are allowed to access the Camio content via the link. When there are no collaborators, then anyone with the link can access its content without authentication.

HTTP Request

POST https://camio.com/api/users/me/camios

Body

Name	Type	Description
id	string	Required.
collaborators	Dictionary	Includes users and domains to which access is restricted.
users	Dictionary	Keys are the user’s email address in lowercase.
domains	Dictionary	Keys are the domains in lowercase.
email	string	Email address of an individual user.
domain	string	The domain to allow like acme.com to allow joe@acme.com, sue@acme.com, etc.
role	string	viewer, editor, or admin.

Create Camio Download

Create a Download that includes all content of the Camio. This API endpoint references Camios that have already been created by a user with the /users/me/camios endpoint.

The JSON response is:

[
    {
        "To Be Determined":"soon"
    }
]

The POST must include an OAuth token identifying the requesting user, since that user will receive an email notification once the download is ready.

Currently, downloads can only be created (no listing, GET, or DELETE) and the :view_token parameter can be supplied only in the URL itself (any JSON in the POST body is ignored).

HTTP Request

POST https://camio.com/api/camios/:view_token/downloads

URL Parameters

Name	Description	Details
view_token	The Camio view_token.	string, required, example: AxqTV1abzQ

Delete Camio

An example request is:

curl \
    -H "Authorization: token abc123" \
    -X DELETE \
    https://camio.com/api/users/me/camios?view_token=vtok123

The response is:

204 (No Content)

HTTP Request

DELETE /api/users/me/camios

URL Parameters

Name	Description	Details
view_token	The token view_token returned by the creation of the Camio.	string, required.

Timelapses

Camio creates query-based timelapse videos from search results. So rather than being restricted only to linear time progressions, Camio timelapses summarize the events that matter most to you in any particular scene.

Create a Timelapse

The minimal input payload is query.text like:

{
    "query": {
        "text": "Liverpool 8am EDT January 1, 2018 to 5pm January 8, 2018 sue@gmail.com"
    }
}

Sample response:

{
    "auth_token": "AQ9COF90uVCdwquDJ5I",
    "date_created": "2018-01-31T19:32:13.072-0000",
    "query": {
        "text": "Liverpool 8am EDT January 1, 2018 to 5pm January 8, 2018 sue@gmail.com",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.132 Safari/537.36"
    },
    "server": "https://camio.com",
    "server_name_user_request": "camio.com",
    "server_user_request": "https://camio.com",
    "timelapse_request": {
        "command": "make_timelapse",
        "date_requested": "2018-01-31T19:32:13.072-0000",
        "maximum_runtime_seconds": 600,
        "query": {
            "text": "west 8am to 9am jcmaslan@gmail.com",
            "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.132 Safari/537.36"
        },
        "reencoding_params": {
            "crf": 28,
            "fps": 30,
            "maxrate": "8000k"
        },
        "timelapse_params": {
            "fph": 1200,
            "jpeg_quality": 10
        }
    },
    "user_id": "117677"
}

The creation of a timelapse movie requires only query.text that includes a timerange constraint as in the example shown.

Liverpool 8am EDT January 1, 2018 to 5pm January 8, 2018 sue@gmail.com

However, you can optionally include the specification of both the creation and encoding of the timelapse by also including timelapse_request that specifies one or both of reencoding_params and timelapse_params.

HTTP Request

PUT https://camio.com/api/users/me/timelapses

Body

Name	Description	Details
query	Only query.text is required.	JSON object, required.
timelapse_request	The specification for the creation of the timelapse (timelapse_params) and/or its final video encoding (reencoding_params).	JSON object, optional.
reencoding_params	The encoding for the output timelapse video.	JSON object, optional.
timelapse_params	The specification for the output timelapse video.	JSON object, optional.
crf	The ffmpeg CRF value that controls the video encoding quality.	Integer, optional.
fps	The frames per second of the output timelapse video.	Integer, optional.
maxrate	The ffmpeg maxrate for the output timelapse video.	String, optional.
fph	Frames per hour extracted from the original source video.	Integer, optional.
jpeg_quality	The value used for the ffmpeg -q:v parameter.	Integer, optional.

Upload Token

An Upload Token is an encrypted string that permits only the uploading of content. It provides no access to content.

Get Upload Token

An example request is:

curl \
    -H "Authorization: token abc123" \
    https://camio.com/api/users/me/tokens/upload

The JSON response is:

"AQBrSFvOPxQj2prnCh2wvocHnAbu_5szaBeFdQsktgE4Vw"

This retrieves the Upload Token only for the currently authenticated user.

HTTP Request

GET https://camio.com/api/users/me/tokens/upload

Get Upload Token Hint

An example request is:

curl \
    -H "Authorization: token abc123" \
    https://camio.com/api/tokens/AQBrSFvOPxQj2prnCh2wvocHnAbu_5szaBeFdQsktgE4Vw/hint

The JSON response is:

{"email":"test@..."}

Sometimes camera installers need to validate that a particular Upload Token corresponds to the user that owns the cameras being installed. So this GET or POST request returns a hint to display a portion of the email address of the user that owns the upload_token. The request requires authentication, but the requester doesn’t have to be the owner of the upload_token.

HTTP Request

GET https://camio.com/api/tokens/:upload_token/hint

or

POST https://camio.com/api/tokens/:upload_token/hint

URL Parameters

Name	Description	Details
upload_token	The Upload Token you’d like to validate with a response containing a hint displaying the user that owns the Upload Token.	string, required, example: AQBrSFvOPxQj2prnCh2wvocHnAbu_5szaBeFdQsktgE4Vw

Readings

The /api/search response includes sensor_data:

{
    "query": {...},
    "result": {
        "bucket_type": "event",
        "buckets": [
            {
                "bucket_id": "ag1zfmNhbWlvbG9nZoyOTowMi45NjYwMDAM",
                "sensor_data": [
                    {
                        "accelerometer_x": -0.2587,
                        "accelerometer_y": 6.1552,
                        "accelerometer_z": 7.6353,
                        "location_accuracy": 19.35484,
                        "location_lat": 37.58162,
                        "location_lng": -122.36906,
                        "sound_level": 67.353,
                        "timestamp": "2016-01-01T16:49:54.061-0800"
                    }
                ],
                "labels": [
                    "door opened",
                    "_ml_human"
                ],
                ...
            },
            ...
        ]
    }
}

Readings enable arbitrary sensor data to be correlated with video events returned in Search results. The timestamp of the Reading is used to correlate the Reading with the video events that span that timestamp.

The Search results include sensor_data whenever any of the search result buckets have Readings associated with them.

Camio accepts multiple data formats for these Readings. The examples are illustrated with the data format used by the AndroSensor app. Please contact us to request support for a particular data format.

Create Readings

Example requests with only location data:

curl \
    -H "Content-Type: application/json" \
    -d '[{"timestamp": "2017-05-03T17:04:51.460+0800", "location_lat": 30.54316833333333, "location_lng": 104.07076333333335, "location_accuracy": 4.300000190734863}]' \
    -X PUT https://camio.com/api/users/xyzpdq123/devices/BOAT1/readings

and with 4G/LTE camera format:

curl \
    -H "Content-Type: application/json" \
    -d '{"sensordata": [{"utc_time"": "2017-05-03T17:04:51.460+0800", "location": {"latitude": 30.54316833333333, "longitude": 104.07076333333335, "accuracy": 4.300000190734863}}]}' \
    -X PUT https://camio.com/api/users/xyzpdq123/devices/BOAT1/readings

The JSON response is:

["r1"]

The command on the right associates a single latitude and longitude with any video event that spans the timestamp 2017-05-03T17:04:51.460+0800.

HTTP Request

POST https://camio.com/api/users/:upload_token/devices/:device_id/readings

URL Parameters

Name	Description	Details
upload_token	the Upload Token of the account or the value me if using OAuth Authorization header instead.	string, optional, example: xyzpdq123.
device_id	any String that uniquely identifies the device within your account.	string, required, example: BOAT1.

Query Parameters

Name	Description	Details
camera_name	the name of the camera to which these readings apply if they don’t apply to all of the user’s cameras.	string, optional, example: starboard.

Annotations

Annotations enable arbitrary labels to be addeded to video events. For example, you may want to annotate video events with access control labels like “door opened” or with sensor interpretations like “collision”.

Annotations must include a timestamp so that they can be correlated with the video events that span that timestamp.

Create Annotations

An example request is:

curl \
    -H "Authorization: token abc123"
    -H "Content-Type: application/json" \
    -d ''{"annotations":[{"timestamp":"2018-11-27T17:04:51.460+0800", "cameras":[{"labels": ["Door1"]}], "labels_to_add": ["unlocked"]}]}'' \
    -X PUT https://camio.com/api/annotations

The JSON response is:

{
    "annotations": {},
    "pending_annotations": [
        {
            "cameras":[{"labels": ["Door1"]}],
            "labels_to_add": ["unlocked"],
            "labels_to_remove": [],
            "timestamp": "2018-11-27T17:04:51.460+0800"
        }
    ]
}

If the annotation references a timestamp for a video Event that has not yet been indexed in the cloud, then the response field pending_annotations will include those annotations that will be applied as soon as the Event arrives to the server after being fetched from Camio Box.

HTTP Request

PUT https://camio.com/api/annotations

Body

The JSON body of the request can optionally include cameras, where each camera object is identified either by its name or its labels.

Name	Description	Details
annotations	The list of annotations	List, required.
timestamp	The ISO 8601 date string	String, required.
labels_to_add	The list of string labels to add to Events that span the timestamp.	List of string, optional.
labels_to_removed	The list of string labels to remove from Events that span the timestamp.	List of string, optional.
cameras	The list of cameras to include. If empty, then all cameras are included.	List of camera objects, optional.

Create Annotations (without OAuth)

An example request is:

curl \
    -H "Content-Type: application/json" \
    -d '[{"timestamp":"2017-05-03T17:04:51.460+0800","labels_to_add":["unlocked"],"labels_to_remove":[]}]' \
    -X PUT https://camio.com/api/users/xyzpdq123/devices/BOAT1/annotations

The JSON response is:

{
    "ag1zfmNhbc29uDA": {
        "labels_to_add": [
            "unlocked"
        ],
        "labels_to_remove": []
    },
    "agDNkMy5qc29uDA": {
        "labels_to_add": [
            "unlocked"
        ],
        "labels_to_remove": []
    }
}

The command on the right associates the label door opened with any video event that spans the timestamp 2017-05-03T17:04:51.460+0800.

Unlike Readings, which can be created prior to the creation of their corresponding video events, Annotations must arrive after your video events have been created. i.e. your PUT /api/users/:upload_token/devices/:device_id/annotations must happen after the Camio servers have received your video content.

HTTP Request

PUT https://camio.com/api/users/:upload_token/devices/:device_id/annotations

URL Parameters

Name	Description	Details
upload_token	the Upload Token of the account or the value me if using OAuth Authorization header instead.	string, optional, example: xyzpdq123.
device_id	any String that uniquely identifies the device within your account.	string, required, example: BOAT1.

Response

The JSON response is a dictionary keyed by event_id to be annotated with the list of labels_to_add and labels_to_remove.

Interactions

This API endpoint is used only by Camio’s own client apps or by partner apps that display video events in customized video viewers. It’s a POST-only endpoint that records user interactions with Events as input to Camio’s Machine Learning that ranks the importance of Events.

Create an Interaction

An example of the body of the JSON request is:

{
    "actions": [
        {
            "action_date": "2016-01-18T15:46:56.049-0800",
            "action_type": "skim",
            "camera": "outdoor",
            "common_context": [
                "Ni0wMS0xNlQxNzoyOToxNy4yOTIwMDAM",
                "Ni0wMS0xNlQxNzoyNzo0OC40ODQwMDAM",
                "Ni0wMS0xNlQxNzowODozMy4xNTgwMDAM",
                "Ni0wMS0xNlQxNjo1Mzo1NS40MTkwMDAM",
                "Ni0wMS0xNlQxNjozOTozMy45NjkwMDAM",
                "Ni0wMS0xNlQxNjoyNjoyMS4xNTAwMDAM",
                "Ni0wMS0xNlQwMDowODo0MS41MTYwMDAM",
                "Ni0wMS0xNVQyMjowMTo1OC40NzIwMDAM",
                "Ni0wMS0xNlQxOTo1MDoxOS43NzEwMDAM",
                "Ni0wMS0xNlQxODo0MTo0NC4yOTYwMDAM",
                "Ni0wMS0xNlQxODo0MToxMi4wOTEwMDAM",
                "Ni0wMS0xOFQwMDo1MToyOC45NDMwMDAM",
                "Ni0wMS0xOFQwMDo1NDo1Ni42MTQwMDAM",
                "Ni0wMS0xOFQwMDo1Njo0Ni40MDUwMDAM",
                "Ni0wMS0xOFQwMTowNzozMy44MDMwMDAM",
                "Ni0wMS0xOFQwNDozNDo0OC43MDUwMDAM",
                "Ni0wMS0xOFQwNjo0MjoxNi4xNDIwMDAM",
                "Ni0wMS0xOFQxMzoyMzoyOS4yNjkwMDAM",
                "Ni0wMS0xOFQxNToxNjoyNC4wNTQwMDAM",
                "Ni0wMS0xOFQxNTo0NjozMi45ODkwMDAM"
            ],
            "event_id": "Ni0wMS0xN1QyMjowMDo1Mi41MzgwMDAM",
            "particular_context": [],
            "skim_direction_changes": 4,
            "total_frames_in_event": 15,
            "total_frames_viewed": 22,
            "unique_frames_viewed": 12
        }
    ],
    "device_type": "pc",
    "first_event_date": "2016-01-17T22:00:52.538-0000",
    "hash": "#search;q=people+approaching+outdoor+walkway+7am+yesterday+in+shades"
}

The response is:

204 (No Content)

Specify the details of the interaction as JSON in the POST body.

HTTP Request

POST https://camio.com/api/users/me/interactions

Body

Name	Type	Description
first_event_date	string	The earliest date of any event included in the interaction.
device_type	string	The type of device on which the action was performed ( “pc”, “tablet”, “phone” ).
actions	List of objects	List of Action objects.
hash	string	optional, for browser-based viewers that maintain state in the url hash.

Action object

Name	Type	Description
event_id	string	“e123”
action_type	string	required, up, down, share, hide, unhide, enlarge, play, skim, star.
action_date	string	Date on which the user interaction occurred. e.g. “2016-01-18T15:46:56.049-0800”
events_in_view	List of strings	The event ids that were in view at the time of the user interaction.
total_frames_in_event	integer	The total number of frames in the event itself; even though the server knows this number, supplying this value is appreciated to reduce server processing costs.
total_frames_viewed	integer	The total number of frames actually viewed by the user.
unique_frames_viewed	integer	The actual number of unique frames that were viewed by the user prior to the action.
device_type	string	The type of device on which the action was performed ( “pc”, “tablet”, “phone” ).
skim_direction_changes	integer	When the user scrubs back-and-forth while previewing the frames of event, this is the number of times that the user changed direction.
common_context	List	TBD
particular_context	List	TBD

Settings

This endpoint gets and sets the user’s notification and host preferences. It also includes the user’s Upload Token in the GET response even though the Upload Token cannot be modified directly with a POST (the Upload Token changes only in response to the user changing his/her Upload Code which is not supported in the API).

Get Settings

Fetch the user’s current settings.

The JSON response is:

{
    "hosts": {
        "ignored_hosts": {
            "103944911981764022143": {
                "date_updated": "2018-10-28T20:11:32.022-0000",
                "host": {
                    "email": "host1@example.com",
                    "user_id": "103944911981764022143"
                }
            },
            "105319691355263881122": {
                "date_updated": "2018-10-28T20:11:32.022-0000",
                "host": {
                    "email": "host2@example.com",
                    "user_id": "105319691355263881122"
                }
            }
        }
    },
    "notifications": {
        "motion_alerts" : {
            "state" : "ON",
            "method" : "PUSH",
            "options" : ""
        },
        "camera_diagnostics" : {
            "state" : "ON",
            "method" : "EMAIL",
            "options" : ""
        },
        "announcements" : {
            "state" : "ON",
            "method" : "EMAIL",
            "options" : ""
        },
        "newsletters" : {
            "state" : "ON",
            "method" : "EMAIL",
            "options" : ""
        },
        "camio_daily" : {
            "state" : "ON",
            "method" : "EMAIL",
            "options" : ""
        }
    },
    "upload_token" : "ABQR123",
    "recording_enabled" : true
}

HTTP Request

GET https://camio.com/api/users/:user/settings

Body

Notification Attributes

Name	Description	Details
user	The email address of the account owner or me for the signed-in user.	String, required, example: jane@example.com
hosts	The object describing preferences in the visibility of Hosts.	Object, optional.
notifications	The dictionary of notification preferences by type of notification.	Dictionary.
recording_enabled	false to override the settings of all cameras to stop saving uploads on the server.	boolean.
upload_token	The read-only Upload Token for the user’s account.	string.

Notifications Types

Name	Description	Details
motion_alerts	Sent when interesting motion is detected in specific zones and cameras.	NotificationPreference object.
camera_diagnostics	Sent when a problem with a particular camera is detected.	NotificationPreference object.
announcements	Info on new features, enhancements and changes.	NotificationPreference object.
newsletters	Tips, news, and information related to uses of Camio.	NotificationPreference object.
camio_daily	Daily summary of interesting events.	NotificationPreference object.

ignored_hosts

The hosts object has an ignored_hosts dictionary keyed by the user_id of the host account owner. To hide a particular host account that has invited the authenticated user as a Guest, add the host’s user_id to the ignored_hosts dictionary. HTTP PUT replaces ignored_hosts and HTTP POST patches ignored_hosts.

Get Settings (Local Camio Box)

An example request is:

curl http:192.168.1.57:8080/box/settings

The JSON response is:

{
  "device_id": "ZADfg23_98kuS-3FyLv2oxbPrsOP56wlUUde8X2B_7B2hBv3-t56bk-sRoBVgaonxCMpi4CAmLkvmT0fz",
  "user-agent": "Linux (x86/64) Camio Box VirtualBox 2017-04-22:ab234badsfb293nas9db9f7231arereds",
}

Fetch the settings from a locally running Camio Box on your network that is operating as an API endpoint for batch imports.

This endpoint serves as a simple way to get some necessary information about the Camio Box you are using for segmentation. To POST content to Box, you’ll need to supply the device_id as a form of a shared secret and you’ll need to supply the same value when registering a camera for batch imports.

HTTP Request

GET http://192.168.1.57/box/settings

Update Settings

The POST must include an OAuth token for the signed-in user in the HTTP Authorization Header.

HTTP Request

POST https://camio.com/api/users/:user/settings

Body

Name	Description	Details
user	The email address of the account owner or me for the signed-in user.	String, required, example: jane@example.com
hosts	The object describing preferences in the visibility of Hosts.	Object, optional.
notifications	The dictionary of notification preferences by type of notification. See the NotificationPreference values in the table below.	Dictionary of NotificationPreference objects.
recording_enabled	true or false to enable or disable recording of uploaded content.	If false, then this value overrides the settings for each individual camera.
upload_token	This is a read-only value that cannot be changed by the caller.	When present in a POST/PUT/PATCH, this value is ignored.

NotificationPreference attributes

Name	Description	Details
state	The “ON” or “OFF” state of the notification type.	string, required. “ON” or “OFF”.
method	The method of delivery for the particular notification type.	string, required. “EMAIL” or “PUSH”.
options	DEPRECATED in favor of pinned queries.	string, optional.

Profile

The user’s profile is used to interpret times and dates in the text parameter of the Search API that omit a timezone specification.

For example, the query text “7am to 8am” performed by a user whose profile has timezone_offset of -0700 will search from 2pm GMT to 3pm GMT. That is, this API call:

https://camio.com/api/search/?text=7am+to+8am

results in this date interpretation:

"earliest_date_allowed":"2017-07-21T14:00:00.000-0000", "latest_date_allowed":"2017-07-21T15:00:00.000-0000"

The profile may also include a first_name and last_name used to display a friendly name instead of an email address alone in the list of Accounts in the Search Panel.

Get a Profile

An example command:

curl \
    -H "Authorization: token xyzauthtoken" \
    https://camio.com/api/users/test%40example.com/profile

An example response:

{
    "email": "test@example.com",
    "first_name": "Test",
    "last_name": "Account",
    "timezone": {
        "timezone_offset": "-0700"
    },
    "user_id": "user123",
    "user_alias": "Test Account"
}

Get an existing user profile.

HTTP Request

GET https://camio.com/api/users/:user/profile

Create a Profile

An example command:

curl \
    -H "Content-Type: application/json" \
    -H "Authorization: token xyzauthtoken" \    
    -d '{"first_name":"Test","last_name":"Account","timezone":{"timezone_offset": "-0700"}}' \
    -X POST https://camio.com/api/users/test%40example.com/profile

An example response:

{
    "email": "test@example.com",
    "first_name": "Test",
    "last_name": "Account",
    "timezone": {
        "timezone_offset": "-0700"
    },
    "user_id": "user123",
    "user_alias": "Test Account"
}

HTTP Request

POST https://camio.com/api/users/:user/profile

URL Parameters

The input payload may specify timezone using either timezone_offset or timezone_offset_minutes (if both were specified accidentally, then the timezone_offset value trumps the other value).

Name	Description	Details
first_name	First name.	string, optional.
last_name	Last name.	string, optional.
timezone	Object with either of the fields timezone_offset or timezone_offset_minutes	Object, optional.
timezone_offset	a 5-character string with the offset from GMT.	string, optional. e.g. "-0700".
timezone_offset_minutes	The integer returned from javascript’s getTimezoneOffset().	integer, optional. e.g. 420.

Data

Both the /api/data/counters/events and /api/data/counters/incidents endpoints serve a Data Source that supports the Google Visualization API Query Language so that it’s easier to import data into spreadsheets and applications.

The default output format is out:json. You can request a different output format by using the tqx URL Parameter with the key/value pairs out:csv, out:html and out:tsv-excel.

For example, get HTML output from a query like this:

https://camio.com/api/data/counters/events?tq=select%20camera_name,sum(events_uploaded_count)%20group%20by%20camera_name&tqx=out:html

And get CSV output from that same query with the URL Paramter &tqx=out:csv like this:

https://camio.com/api/data/counters/events?tq=select%20camera_name,sum(events_uploaded_count)%20group%20by%20camera_name&tqx=out:csv

You can also view interactive charts of these counters on your Dashboard at camio.com/dashboard.

Event Counters

An example request:

curl \
    -H "Authorization: token xyzauthtoken" \
    https://camio.com/api/data/counters/events/?tzo=480&period=3d&tq=select%20counter_date_hour,camera_name,sum(events_uploaded_count)%20group%20by%20counter_date_hour,camera_name%20order%20by%20counter_date_hour%20asc&tqx=reqId%3A0

The response is JSON for the Google Visualization API:

{
    "reqId": "0",
    "sig": "889565750",
    "status": "ok",
    "table": {
        "cols": [
            {
                "id": "counter_date_hour",
                "label": "counter_date_hour",
                "pattern": "",
                "type": "datetime"
            },
            {
                "id": "camera_name",
                "label": "camera_name",
                "pattern": "",
                "type": "string"
            },
            {
                "id": "sum-events_uploaded_count",
                "label": "sum events_uploaded_count",
                "pattern": "",
                "type": "number"
            }
        ],
        "rows": [
            {
                "c": [
                    {
                        "v": "Date(2019,1,13,19,0,0)"
                    },
                    {
                        "v": "Liverpool"
                    },
                    {
                        "v": 10.0
                    }
                ]
            },
            {
                "c": [
                    {
                        "v": "Date(2019,1,13,19,0,0)"
                    },
                    {
                        "v": "east"
                    },
                    {
                        "v": 20.0
                    }
                ]
            },
            {
                "c": [
                    {
                        "v": "Date(2019,1,13,19,0,0)"
                    },
                    {
                        "v": "west"
                    },
                    {
                        "v": 0.0
                    }
                ]
            },
            ...

Please use Incident Counters instead for the critical data-loss counters.

HTTP Request

GET https://camio.com/api/data/counters/events

URL Parameters

Name	Description	Details
tq	A query written in Google Visualization API query language, specifying how to filter, sort, or otherwise manipulate the returned data. The string does not need to be quoted.	string, optional.
tqx	A set of colon-delimited key/value pairs for standard or custom parameters. Pairs are separated by semicolons. out:json is the default; out:csv, out:html and out:tsv-excel are also supported.	string, optional, example &tqx=out:csv
user	The email address of the user that owns the account	string, optional, example test@example.com
period	The number of days of historical data to retrieve, expressed in units like 3d for 3 days.	string, optional, default 7d

Data Source Fields

The Data Source for hourly counters includes the following fields.

Name	Description	Details
camera_name	The name of the camera of the counter.	TEXT
counter_date	The DATETIME of the beginning of the hour of the counter.	DATETIME
user_id	The user_id of the owner of the account.	TEXT
hour	The numeric hour 0-23 of the counter.	NUMBER

Counter Names

Each counter name is constructed with with some combination of the pattern:

___

These are examples of counters, and the descriptions of each element of the pattern is in the table below.

• events_uploaded_count
• events_uploaded_size_bytes
• events_uploaded_timelapse_count
• events_uploaded_timelapse_size_bytes
• events_uploaded_nonmotion_count
• events_uploaded_nonmotion_size_bytes
• events_uploaded_motion_count
• events_uploaded_motion_size_bytes
• movies_uploaded_count
• movies_uploaded_size_bytes
• movies_uploaded_timelapse_count
• movies_uploaded_timelapse_size_bytes
• movies_uploaded_nonmotion_count
• movies_uploaded_nonmotion_size_bytes
• movies_uploaded_motion_count
• movies_uploaded_motion_size_bytes
• events_important_count
• events_important_size_bytes
• movies_important_count
• movies_important_size_bytes
• etc…

Name	Description	Details
object	The thing that’s being counted like movies, events, thumbnails, downloads, uploads, options_changed_restart.	string, required.
operation	The operation performed on the object being counted like generated, requested, uploaded, segmented.	string, optional.
classification	Camio’s classification of the object like motion, nonmotion, timelapse.	string, optional.
units	Currently, there are only two units: count for an integer total and size_bytes for an integer total of bytes.	string, required.

Deprecated Data Source Fields

Though these fields are still included in the Data Source, they’re deprecated.

Name	Description	Details
count	The total number of Events analyzed in the hour of the counter.	NUMBER
counter_date_formatted	The counter_date formatted as a string like “2017-08-27” (“yyyy-MM-dd”)	TEXT

Incident Counters

An example request:

curl \
    -H "Authorization: token xyzauthtoken" \
    https://camio.com/api/data/counters/incidents/?tzo=480&period=3d&tq=select%20counter_date_hour,camera_name,sum(counter_value)%20where%20counter_name%20=%20%27segmentation_process_restart_count%27%20group%20by%20counter_date_hour,camera_name%20order%20by%20counter_date_hour%20asc&tqx=reqId%3A0

The response is javascript for the Google Visualization API:

{
    "reqId": "0",
    "sig": "661041890",
    "status": "ok",
    "table": {
        "cols": [
            {
                "id": "counter_date_hour",
                "label": "counter_date_hour",
                "pattern": "",
                "type": "datetime"
            },
            {
                "id": "camera_name",
                "label": "camera_name",
                "pattern": "",
                "type": "string"
            },
            {
                "id": "sum-counter_value",
                "label": "sum counter_value",
                "pattern": "",
                "type": "number"
            }
        ],
        "rows": [
            {
                "c": [
                    {
                        "v": "Date(2019,0,16,5,0,0)"
                    },
                    {
                        "v": "Backyard"
                    },
                    {
                        "v": 93.0
                    }
                ]
            },
            {
                "c": [
                    {
                        "v": "Date(2019,0,16,17,0,0)"
                    },
                    {
                        "v": "Backyard"
                    },
                    {
                        "v": 132.0
                    }
                ]
            },
            ...

Unlike Event counters, Incident counters sum(counter_value) rather than having unique column names for each counter value. Incident counters report the sum per 15-minute interval instead of an hourly total.

For example, to retrieve a CSV file containing the most recent incidents across all accounts associated with the server_name video.acme.com, execute the query:

https://video.acme.com/api/data/counters/incidents/?server_name=video.acme.com&tq=select%20*%20order%20by%20counter_date_hour%20desc&tqx=out:csv

Use the /api/data/counters/incidents endpoint for these counters for much faster results. These are critical counters, and any non-zero value reveals data loss problems. See the definition of each counter.

Name	Non-zero value meaning
movies_discarded_count	The Box gateway is overloaded with too many streams.
events_purged_count	Uplink bandwidth is insufficient to index Events.
movies_purged_count	Uplink bandwidth is insufficient to upload video files.
segmentation_process_restart_count	The LAN connection between the camera/NVR and the Box gateway is unstable.

HTTP Request

GET https://camio.com/api/data/counters/incidents

URL Parameters

Name	Description	Details
server_name	The private-labeled server name (e.g. video.acme.com). This parameter replaces the user parameter so that results span all users associated with the server_name. Any authorized support staff memember associated with the domain of the server_name has permission to retrieve incident counters of all users of that same domain.	string, optional.
tq	A query written in Google Visualization API query language, specifying how to filter, sort, or otherwise manipulate the returned data. The string does not need to be quoted.	string, optional.
tqx	A set of colon-delimited key/value pairs for standard or custom parameters. Pairs are separated by semicolons. out:json is the default; out:csv, out:html and out:tsv-excel are also supported.	string, optional, example &tqx=out:csv
user	The email address of the user that owns the account. The user parameter is ignored when server_name is specified in order to report across all users.	string, optional, example test@example.com

Spreadsheets

To see the data in an always-up-to-date Google Spreadsheet, you can use the ImportData function with your Camio Upload Token for Authorization. For example, if you’ve pasted your Upload Token into cell A1, then your formual might look like this:

=ImportData(CONCATENATE("https://camio.com/api/data/counters/events/?token=",$A$1,"&period=7d&tq=select%20camera_name,sum(events_uploaded_count) group by camera_name&tqx=out:csv"))

There’s an example spreadsheet at: http://go.camio.com/data-api-example

Commands

Create a Command

Example request is:

curl \
    -H "Authorization: token YOURTOKEN" \
    -d '{"command":"REQUEST_UPLOAD","event_id":"ag1zfmNhbW***REDACTED***iLWEY5"}' \
    -X PUT https://camio.com/api/users/me/commands

The 200 response is informational only and simply reflects the movies that will be uploaded by this request.

{
    "device_id": "AQBHmiWc6Z8DSg4tdD***REDACTED***qpBkMrOIwnr",
    "event_id": "ag1zfmNhbW***REDACTED***iLWEY5ZWM5",
    "ii_level": 2,
    "local_camera_id": "00E04C52A539.0",
    "movies": [
        {
            "content_type": "video/mp4",
            "duration_sec": 10.57,
            "format_info": {
                "codec_name": "h264",
                "movie_hash": "4bbae2b3098a89501fe0f1e07bcd783cd942ccd7",
                "profile": "Constrained Baseline"
            },
            "id": "00E04C52A539.0_2019-02-16T04:29:57_baee2a1f-2767-4cac-a0c3-cb606244162d.mp4",
            "playback_speed_ratio": 1.0,
            "server_id": "mv-117550000798386757677-00E04C52A539.0_2019-02-16T04:29:57_baee2a1f-2767-4cac-a0c3-cb606244162d.mp4",
            "timestamp": {
                "date": "2019-02-16T04:29:57",
                "meta_class": "datetime.datetime"
            }
        },
        {
            "content_type": "video/mp4",
            "duration_sec": 10.57,
            "format_info": {
                "codec_name": "h264",
                "movie_hash": "f40da83614330cccdb66eaf79ea9381fd18ec91f",
                "profile": "Constrained Baseline"
            },
            "id": "00E04C52A539.0_2019-02-16T04:30:08_11203ad4-0b85-4a16-9df7-1f047b07e416.mp4",
            "playback_speed_ratio": 1.0,
            "server_id": "mv-117550000798386757677-00E04C52A539.0_2019-02-16T04:30:08_11203ad4-0b85-4a16-9df7-1f047b07e416.mp4",
            "timestamp": {
                "date": "2019-02-16T04:30:08",
                "meta_class": "datetime.datetime"
            }
        }
    ],
    "server_name": "camio.com",
    "user_agent": "curl/7.30.0",
    "user_id": "117550000798386757677"
}

“command”	Description
REQUEST_UPLOAD	Adds a high priority task to the Box task queue to upload the videos associated with an event_id.

The REQUEST_UPLOAD command is useful when a stream is connected in metadata-only mode, which uploads and indexes only the Event’s metadata without uploading its associated video files.

When using the Camio web app, this command is triggered automatically when you click on an Event thumbnail to play the video. So the REQUEST_UPLOAD command is required only for API clients that need to control the requested video files directly without relying on the web app. The typical usage would be this sequence:

1. Receive a Hook callback that includes the event_id that triggered the Hook.
2. Attempt to fetch the url of each video in videos enumerated in the payload of the analysis callback.
3. Upon 404 response from the video url, use PUT /api/users/me/commands with REQUEST_UPLOAD for the event_id as in the example shown here.
4. Retry the fetch of each url attempted in step 2 above after allowing a few seconds for the upload to complete (optimal wait time depends on uplink bandwidth and video size).

Response Code	Description
200	The videos of event_id were successfully requested.
400	Either the event_id wasn’t found or the payload of the request was invalid.
401	The Authorization HTTP Header was invalid. Only authenticated users can create the command.
500	The server was unable to retrieve the information required to enqueue the command.

NOTE: It’s possible to receive a 400 or 500 response if you receive pubsub messages directly from the Box gateway prior to the Event’s being uploaded to the cloud. Retry the command in 12 seconds when you know you’re processing real-time Hook callbacks dispatched directly from Box.

RTMP Camera Commands

The commands below enable remote control of RTMP video streams that are connected to Camio. The commands can target either the Camio Box gateway (identified by device_id) or the camera that’s streaming the video (identified by streaming_source_id).

These API endpoints are the subset of commands required for an RTMP streaming device (e.g. a 4G-connected dashcam) to connect to Camio.

Required Commands

Examples of each required command:

curl \
    -d '{"command": "REQUEST_CONFIGURATION", "device_id": "s123", ...}'
    -X PUT https://camio.com/api/devices/commands

curl \
    -d '{"command": "START_STREAMING", "device_id": "s123"}'
    -X PUT https://camio.com/api/devices/commands

curl \
    -d '{"command": "STOP_STREAMING", "device_id": "s123"}'
    -X PUT https://camio.com/api/devices/commands

curl \
    -d '{"command": "REQUEST_FIRMWARE_DOWNLOAD", "device_id": "s123"}'
    -X PUT https://camio.com/api/devices/commands

curl \
    -d '{"command": "REQUEST_FIRMWARE_UPGRADE", "device_id": "s123"}'
    -X PUT https://camio.com/api/devices/commands

curl \
    -d '{"command": "REQUEST_STATE", "device_id": "s123"}'
    -X PUT https://camio.com/api/devices/commands

These are the six commands that a device must support in order to be Camio-ready:

Name	Description
REQUEST_CONFIGURATION	Controls all settings related to streams, sensors, and other commands.
START_STREAMING	Instructs the receiver to begin streaming the video from configuration.streams.live via RTMP to the url specified by the prior REQUEST_CONFIGURATIONcommand for configuration.tasks.rtmp.url
STOP_STREAMING	Instructs the receiver to stop streaming the video from configuration.streams.live
REQUEST_FIRMWARE_DOWNLOAD	Instructs the receiver to begin downloading a new firmware release from the configuration.tasks.firmware.url specified by the prior REQUEST_CONFIGURATION command
REQUEST_FIRMWARE_UPGRADE	Instructs the receiver to apply the firmware upgrade that has been downloaded onto local storage already by a prior REQUEST_FIRMWARE_DOWNLOAD command.
REQUEST_STATE	Instructs the receiver to POST its current state as JSON to the configuration.tasks.state.url that was specified by the prior REQUEST_CONFIGURATION command.

Please contact us for the other optional commands that enable the perferred client-side handling of video/sensor analysis and tasks in collaboration with Camio servers. The minimal set of commands above are geared towards cameras with limited firmware capabilities that must rely only on continuous RTMP streaming as the way to get video to Camio.

Required QR Code Setup

In addition to the six commands above, a Camio-enabled device must also recognize a bootstrapping QR code that specifies the URL from which to GET the first REQUEST_CONFIGURATION command associated with the signed-in user’s account. For example, the camera must read a QR code like this one in order to perform the specified:

GET https://camio.com/api/devices/commands/?device_id=s123

The response from this bootstrapping GET request above is exactly the same format as the response from List all Commands.

List all Commands

An example of retrieving the list of pending Commands:

curl \
    https://camio.com/api/devices/commands/?streaming_source_id=s123

Example response JSON is:

[
    {
        "command": "REQUEST_STATE",
        "device_id": "s123"
    },
    {
        "command": "START_RECORDING",
        "device_id": "s123"
    }
]

All commands are queued for retrieval in first-in-first-out (FIFO) order. So the act of retrieving the list of queued commands also clears the queue of all pending commands.

Note that OAuth isn’t required to retrieve commands; the streaming_source_id or device_id itself serves as a shared secret sufficient to fetch commands for the device.

HTTP Request

GET https://camio.com/api/devices/commands

URL Parameters

Name	Description	Details
streaming_source_id	The unique identifier of the video stream source that will receive the commands.	string, required.
device_id	The unique identifier of the Box when streaming_source_id is omitted.	string, required if streaming_source_id omitted.

Create a Command

To create a Command:

curl \
    -H "Authorization: token xyzauthtoken" \
    -d '{"command": "REQUEST_CONFIGURATION", ...}'
    -X PUT https://camio.com/api/devices/commands

The input payload JSON is a single Command that is exactly the same as the response shown below.

Response from an example REQUEST_CONFIGURATION echos the input JSON:

{
    "command": "REQUEST_CONFIGURATION",
    "configuration": {
        "streams": {
            "live": {
                "audio": {
                    "enabled": false
                },
                "bitrate": 380,
                "enabled": true,
                "fps": 15,
                "height": 480
            },
            "video": {
                "angle": 2,
                "audio": {
                    "enabled": true
                },
                "autoreconnect": 1,
                "bitrate": 2048,
                "enabled": true,
                "fps": 30,
                "height": 1080
            }
        },
        "tasks": {
            "command": {
                "url": "https://camio.com/api/devices/commands/?device_id=s123"
            },
            "firmware": {
                "url": "https://camio.com/api/devices/firmware"
            },
            "rtmp": {
                "network_disconnected_timeout_seconds": 3600,
                "url": "rtmp://hls.camio.com/hls/s123"
            },
            "sensor": {
                "frequency_seconds": 10,
                "network_disconnected_timeout_seconds": 3600,
                "url": "https://camio.com/api/users/xyzpdq/devices/s123/readings"
            },
            "state": {
                "url": "https://camio.com/api/devices/state/?device_id=s123&token=xyzpdq&local_camera_id=00112233445566.0"
            },
            "websocket": {
                "retry_options": {
                    "max_backoff_seconds": 240,
                    "max_doublings": 4,
                    "min_backoff_seconds": 15
                },
                "url": "wss://websockets.camio.com/ws?device_id=s123"
            }
        }
    },
    "device_id": "s123"
}

HTTP Request

PUT https://camio.com/api/devices/commands

URL Parameters

Name	Description	Details
streaming_source_id	The unique identifier of the video stream source that will receive the commands.	string, required.
device_id	The unique identifier of the Box when streaming_source_id is omitted.	string, required if streaming_source_id omitted.

Delete all Commands

Commands are automatically removed from the queue as the client retrieves them, so it’s rare to need this DELETE command. But it may be helpful when a lot of commands were queued for a device that was offline and unable to retrieve them for an extended period of time.

curl \
    -X DELETE \
    https://camio.com/api/devices/commands/?device_id=s123

Response JSON is:

204 (No Content)

HTTP Request

DELETE https://camio.com/api/devices/commands

URL Parameters

Name	Description	Details
device_id	The unique identifier of the Box or stream.	string, required.

Devices

This endpoint provides information about the configuration and state of the user’s Camio Box devices and connected video streams.

If you are the owner of the device, or if you have Can Manage privileges as Guest of the owner, then you see all information. If you are a support staff member of a Camio partner for a particular domain, and you have verified your email address as belonging to that same domain, then you can see redacted output that’s helpful for customer technical support.

List all Devices

For each device listed, there is a config section and and state section that describe the permanent configuration of the Box and the transient state of the Box respectively.

Example command is:

curl \
    -H 'Authorization: token gKBVf2b7' \
    https://camio.com/api/devices?user=sarah%40example.com&pretty_print=1

Sample response is a list of devices and streams:

[
  {
    "device_id": "AQD5aZ1m***redacted***",
    "last_updated": {
      "meta_class": "datetime.datetime",
      "date": "2018-01-19T19:33:17.985"
    },
    "date_updated": "2018-01-19T19:33:17.985-0000",
    "user_id": "cc:123456",
    "mac_address": "001E06346D55",
    "name": "Office Camio Box",
    "config": {
      "device_id": "AQD5aZ1m***redacted***",
      "user_id": "cc:123456",
      "mac_address": "001E06346D55",
      "camera_info": {
        "ACCC8E0C34E9.0": {
          "camera_id": "cc:123456:ACCC8E0C34E9:ACCC8E0C34E9.0",
          "user_id": "cc:123456",
          "mac_address": "ACCC8E0C34E9",
          "last_updated": {
            "meta_class": "datetime.datetime",
            "date": "2018-01-19T19:03:24.444"
          },
          "plan": {
            "user_id": "cc:123456",
            "user_email": "sarah@example.com",
            "camera_name": "Office Entrance",
            "vision_services": {},
            "expiration_store_movies": [
              {
                "meta_class": "datetime.datetime",
                "date": "2017-09-15T22:16:55.000"
              },
              {
                "meta_class": "datetime.datetime",
                "date": "2017-09-15T22:16:55.000"
              },
              {
                "meta_class": "datetime.datetime",
                "date": "2017-09-15T22:16:55.000"
              }
            ]
          },
          "options": {
            "create_motion_events": true,
            "create_nonmotion_events": true,
            "write_motion_movies": true,
            "write_nonmotion_movies": true,
            "write_motion_thumbnails": true,
            "write_nonmotion_thumbnails": true,
            "zones": "[{\"name\":\"door\",\"polygons\":[{\"points\":[{\"x\":0.5697889290407359,\"y\":0.4369158878504673},{\"x\":0.5164450317621544,\"y\":0.566810060348132},{\"x\":0.46507859632062654,\"y\":0.6363764635514166},{\"x\":0.4463354462401956,\"y\":0.6920819516551596},{\"x\":0.41585280723623563,\"y\":0.7348511938191116},{\"x\":0.37477337824516954,\"y\":0.7913631240133482},{\"x\":0.24691196979137278,\"y\":0.8216012079570499},{\"x\":0.19747740535480993,\"y\":0.7923695936799113},{\"x\":0.13873745628615974,\"y\":0.7429554079833733},{\"x\":0.07570220105124836,\"y\":0.6348580282081975},{\"x\":0.08843148521037243,\"y\":0.4290327792285354},{\"x\":0.11891193590165763,\"y\":0.30511225194889935},{\"x\":0.2121814161891014,\"y\":0.22671689093463424},{\"x\":0.27127803760303354,\"y\":0.17941985302809083},{\"x\":0.29727912530795425,\"y\":0.1737499923365745},{\"x\":0.4528208269414026,\"y\":0.1781467723729015},{\"x\":0.49091770863035716,\"y\":0.19436308588930157},{\"x\":0.5524062084091207,\"y\":0.27957388878273653},{\"x\":0.5641697864416257,\"y\":0.32113940412185593},{\"x\":0.5684748685939554,\"y\":0.43457943925233644},{\"x\":0.5697889290407359,\"y\":0.4369158878504673}]}]}]",
            "rtsp_url_pattern": "rtsp://***redacted***/axis-media/media.amp?camera\u003d",
            "rtsp_url_pattern_python": "rtsp://***redacted***/axis-media/media.amp?camera\u003d1",
            "rtsp_url_params": {
              "port": "554",
              "username": "admin",
              "stream": "1",
              "password": "***redacted***"
            }
          }
        }
      },
      "max_scan_addresses": 1024,
      "auth_failure_cooldown_timeout_seconds": 120
    },
    "state": {
      "camera_info": {
        "ACCC8E0C34E9.0": {
          "live_view_active": false,
          "online": true,
          "stream_state": {
            "code": "200",
            "message": "OK",
            "perc_obtained_frames": 100.0,
            "width": 1280,
            "height": 720,
            "movie_size_bytes": 2643021,
            "frame_rate": 19.100191,
            "codec_name": "h264",
            "bit_rate_kbps": 2100.905,
            "h264_profile": "Baseline"
          },
          "network_configuration_actual": {
            "ip_address": "10.10.10.76"
          }
        }
      },
      "latest_server_contact_date": "2018-01-31T21:01:43.378-0000",
      "online": true,
      "network_configuration_actual": {
        "ip_address": "10.10.10.90"
      },
      "network_configuration": {
        "ip_assignment": "DHCP",
        "ip_address": "",
        "network_mask": "",
        "gateway": "",
        "dns_servers": [
          "8.8.8.8",
          "8.8.4.4"
        ]
      },
      "system_stats": {
        "disk": 30.8,
        "ram": 31.1,
        "cpus": [
          10.0,
          0.0,
          100.0,
          0.0
        ],
        "swap": 0.0
      },
      "queue_stats": {
        "upload_queue_length": 1
      }
    },
    "user_agent": "CamioBox (Linux; odroidc2) Firmware:box-odroidc2-cam.201712100117-a9317ccaaf78af402eb9bab40b0b22619771ac7e",
    "max_streams": 3
  }
]

HTTP Request

GET https://camio.com/api/devices

URL Parameters

Name	Description	Details
user	The email address of the user that owns the device, required only if not the currently authenticated user.	string, optional.
pretty_print	Use the value 1 to return pretty-print JSON	string, optional.

Get a Device

Example command without Authorization:

curl \
    https://camio.com/api/devices?device_id=AQD5aZ1m

Sample response without Authorization includes only the user_id:

{"user_id": "cc:123456"}

Example command with Authorization for a complete response:

curl \
    -H 'Authorization: token gKBVf2b7' \
    https://camio.com/api/devices?device_id=AQD5aZ1m

The no-auth request for a single device_id returns only the user_id associated with that device_id as an admin utility lookup for partners providing support to many users.

HTTP Request

GET https://camio.com/api/devices

URL Parameters

Name	Description	Details
device_id	The unique identifier of the Box.	string, required.

Delete a Device

curl \
    -X DELETE \
    https://camio.com/api/devices/?device_id=s123

Response JSON is:

204 (No Content)

HTTP Request

DELETE https://camio.com/api/devices?device_id=:id

URL Parameters

Name	Description	Details
device_id	The unique identifier of the Box.	string, required.

Create a Device Configuration Request

An example request is:

curl \
    -H "Authorization: token XYZPDQ" \
    -H "Content-Type: application/json" \
    -d '{"device_id":"d123", "network_configuration":{"ip_assignment": "DHCP"}, "movie_storage_type": "default"}' \
    -X PUT https://camio.com/api/devices/requests/configuration

The JSON payload is:

{
    "device_id": "d123",
    "network_configuration": {
        "ip_assignment": "DHCP"
    }
}

The response when there is no network_configuration in the request:

204 (No Content)

Only when network_configuration is in the request, the response is the network configuration command sent to the Box.

200 (No Content)

{
    "command": "REQUEST_NETWORK_CONFIG",
    "device_id": "d123",
    "network_configuration": {
        "ip_assignment": "DHCP"
    }
}

This request changes the configuration of the Camio Box device itself.

The only two supported configuration changes are:

1. network_configuration
2. movie_storage_type

Example of including only movie_storage_type in the request:

{
    "device_id": "AQDMf****REDACTED****vmT0fz",
    "movie_storage_type": "volatile"
}

Since changing the network_configuration is so dangerous (since it can take a Box offline, requiring a factor reset to get it back on the network), we recommend omitting network_configuration from /api/devices/requests/configuration whenever possible. The example on the right changes only the movie_storage_type without touching the network_configuration.

The deprecated configuration changes are:

• concat_motion_events
• concat_nonmotion_events
• do_visual_motion_confirmation

HTTP Request

PUT https://camio.com/api/devices/requests/configuration

Body

Name	Description	Details
movie_storage_type	Use default to let the Box decide, volatile for memory, and disk for on-device SSD. Don’t choose disk unless you have SSD, because otherwise it degrades performance or wears out the storage with frequent writes.	string, optional.
network_configuration	The object with the full specification for the way Box connects to the network. See its member variables defined below.	Object, optional.
ip_assignment	DHCP or STATIC and default is DHCP.	String, required.
ip_address	The local network static IP address when using ip_assignment STATIC.	String, required for STATIC, e.g. 192.168.1.72.
network_mask	The subnet mask.	String, required for STATIC, e.g. 255.255.255.0.
gateway	The local network gateway/router.	String, required for STATIC, e.g. 192.168.1.1.
dns_servers	The Domain Name Servers as list of strings.	List of strings, required for STATIC, e.g. ["8.8.8.8", "8.8.4.4"].

Deprecated Device Configurations

Example of the deprecated configuration change to use Single (vs. Chunked) video file uploads and Basic (vs. Visual) analysis:

curl \
    -H "Authorization: token XYZPDQ" \
    -H "Content-Type: application/json" \
    -d '{"concat_motion_events": true, "concat_nonmotion_events": true, "device_id": "AQDMf****REDACTED****vmT0fz","do_visual_motion_confirmation": false}' \
    -X PUT https://camio.com/api/devices/requests/configuration

{
    "concat_motion_events": true,
    "concat_nonmotion_events": true,
    "device_id": "AQDMf****REDACTED****vmT0fz",
    "do_visual_motion_confirmation": false
}

The example on the right is deprecated but included for clarity.

Name	Description	Details
concat_motion_events	deprecated value of true concatentates all motion videos into a single video per Event.	boolean, default is false.
concat_non_motion_events	deprecated value of true concatentates all videos without motion into a single video per Event.	boolean, default is false.
do_visual_motion_confirmation	deprecated value of false resorts to Basic motion analysis.	boolean, default is true.

Plans

The actual subscription plans are created and maintained in Stripe. See How do I create subscription plans? These APIs enable you to associate specific plans with specific users to automate the display of subscription options available to each individual user when opening the /account page.

List plans offered

Example command is:

curl \
    -H 'Authorization: token gKBVf2b7' \
    https://camio.com/api/plans/offered?user=sarah%40example.com

Sample response is:

{
    "email": "sarah@example.com",
    "plan_ids_offered": [
        "good",
        "better",
        "best"
    ]
}

This retrieves the ids of the subscription plans assigned to appear on the /account page of one particular user.

HTTP Request

GET https://camio.com/api/plans/offered

URL Parameters

Name	Description	Details
user	The email address of the user that will see the specified plans by default on the /account page	string, optional.

Create plans offered

curl \
    -H 'Authorization: token gKBVf2b7' \
    -H 'Content-Type: application/json' \
    -d '{"email": "sarah@example.com", "plan_ids_offered": ["good", "better", "best"]}' \
    -X PUT https://camio.com/api/plans/offered

The response is:

204 (No Content)

When you create custom subscription plans for particular users, you may not want to launch those plans for all other users to see on the /account page. You can send a link to the user with the specific plans enumerated like this: https://camio.com/account/#plans=good,better,best

However, if you’d like those custom plans to appear by default on the /account page of a particular user, then you can use this API to assocate a list of plan_ids_offered with the user’s email using the API command shown on the right.

HTTP Request

PUT https://camio.com/api/plans/offered

URL Parameters

Name	Description	Details
email	The email address of the user that will see the specified plans on his/her account page	string, required.
plan_ids_offerred	The list of plan id values that will be shown by default on the user’s /account page.	list of string, required.

Delete plans offered

curl \
    -H 'Authorization: token gKBVf2b7' \
    -X DELETE https://camio.com/api/plans/offered?user=sarah%40example.com

The response is:

204 (No Content)

HTTP Request

DELETE https://camio.com/api/plans/offered

URL Parameters

Name	Description	Details
user	The email address of the user that will see the specified plans by default on the /account page	string, optional.

List camera plans

Example command is:

curl \
    -H 'Authorization: token gKBVf2b7' \
    https://camio.com/api/cameras/plans?user=sarah%40example.com&pretty_print=1

The response is a list like:

[
  {
    "id": "plus",
    "name": "plus",
    "expiration_date": "2017-09-15T22:16:55.000-0000",
    "num_cameras": 5,
    "num_cameras_assigned": 5,
    "is_subscription": true,
    "camera_ids": [
      "cc:123456:3CEF8CEB06A2:3CEF8CEB06A2.0",
      "cc:123456:4C11BF85829E:4C11BF85829E.1",
      "cc:123456:00B362444392:00B362444392.0",
      "cc:123456:ACCC8E0C34E9:ACCC8E0C34E9.0",
      "cc:123456:4C11BF0B1B8A:4C11BF0B1B8A.0"
    ]
  },
  {
    "id": "basic",
    "name": "basic",
    "expiration_date": "2018-01-31T22:37:30.986-0000",
    "num_cameras": 3,
    "num_cameras_assigned": 2,
    "is_subscription": true,
    "camera_ids": [
      "cc:123456:6F5E4D3C2B1A:6F5E4D3C2B1A.0",
      "cc:123456:E0508B2C2470:E0508B2C2470.0"
    ]
  }
]

For each subscription plan purchased by the user, show the num_cameras purchased and camera_ids that have been assigned to that plan along with its expiration_date.

HTTP Request

GET https://camio.com/api/cameras/plans

URL Parameters

Name	Description	Details
user	The email address of the user that purchased the subscription plans	string, optional.
pretty_print	Use the value 1 to return pretty-print JSON	string, optional.

Get plan Metadata

Example command is:

curl \
    -H 'Authorization: token gKBVf2b7' \
    https://video.acme.com/api/plans/metadata?id=my-best-1

The JSON response is the same as the example shown in Create plan Metadata

HTTP Request

GET https://video.acme.com/api/plans/metadata

NOTE the required use of your own custom domain.

URL Parameters

Name	Description	Details
id	The id of the Metadata.	string, required.

Create plan Metadata

Example command

curl \
    -H 'Authorization: token gKBVf2b7' \
    -H 'Content-Type: application/json' \
    -d '{...}' \
    -X PUT https://video.acme.com/api/plans/metadata

The JSON payload is the same as the 200 response example below without the fields url and stripe_metadata, which are provided by the server.

{
  "id": "my-best-1",
  "storage_duration_days": 90,
  ...
}

The 200 response is:

{
  "id": "my-best-1",
  "url": "https://video.acme.com/api/plans/metadata/?id\u003dmy-best-1",
  "stripe_metadata": {
    "camio_plan_metadata_id": "my-best-1",
    "camio_plan_metadata_url": "https://video.acme.com/api/plans/metadata/?id\u003dmy-best-1"
  },
  "storage_duration_days": 90,
  "allowance_sum": "plan",
  "counter_quotas": {
    "events_uploaded_count": {
      "limit": 36600,
      "overage": 1200,
      "price": 33.0
    },
    "events_label_detection_count": {
      "limit": 0,
      "overage": 1,
      "price": 0.21
    }
    "events_text_detection_count": {
      "limit": 0,
      "overage": 1,
      "price": 0.21
    },
    "timelapse_count": {
      "limit": 0,
      "overage": 1,
      "price": 50.0
    },
    "uploads_size_bytes": {
      "limit": 15000000000,
      "overage": 500000000,
      "price": 44.0
    }
  },
  "timelapses": {
    "on_demand": {
      "extraction": {
        "fph": 3600,
        "jpeg_quality": 10
      },
      "encoding": {
        "crf": 28,
        "fps": 30,
        "maxrate": "8000k"
      }
    },
    "non_motion": {
      "extraction": {
        "fph": 3600,
        "img_size_y": 480
      }
    }
  },
  "rate_quotas": {
    "TEXT_DETECTION": {
      "ii": 2,
      "quota_rules": {
        "capacity": 30,
        "hourly_rate": 15,
        "max_calls_per_event": 1
      }
    },
    "LABEL_DETECTION": {
      "ii": 2,
      "quota_rules": {
        "capacity": 30,
        "hourly_rate": 15,
        "max_calls_per_event": 3
      }
    }
  },
  "filters": {
    "video_upload": {
      "interest_scores": [
        0,
        1,
        2
      ]
    }
  },
  "hashes": {
    "video": "SHA-1"
  }
}

The JSON payload defines the video processing features and service levels of Subscriptions to Plans that reference the camio_plan_metadata_id in their Stripe Plan metadata.

The response from this PUT command includes stripe_metadata, which specifies the keys and values that must be included in the Stripe Plan metadata. For example, your Stripe Plan metadata includes entries like these:

Key	Value
camio_plan_metadata_id	my-best-1
camio_plan_metadata_url	https://camio.acme.com/api/plans/metadata?id=my-best-1

The string keys and values above are supplied by the response from PUT /api/plans/metadata.

NOTE: This API endpoint is for Camio Platform partners and requires a custom Camio domain and Stripe Connect account. You must use your own domain’s API endpoint (e.g. https://video.acme.com/api/plans/metadata) because the server name is used to identify the Stripe Connect account when storing Metadata.

HTTP Request

PUT https://video.acme.com/api/plans/metadata

NOTE the required use of your own custom domain (i.e. video.acme.com rather than camio.com).

JSON body

Name	Description	Details
storage_duration_days	The integer number of days to retain video history before it is purged automatically.	integer, required.
allowance_sum	The method of determining the total budgeted allowance. Use the value plan when you want your total budget to be shared across all cameras on the same plan, and use the value camera when each camera must be billed within its own individual limits.	string, optional. Default is plan.
counter_quotas	Dictionary keyed by the name of the counter.	Object, required.
rate_quotas	Dictionary keyed by the name of the service being throttled.	Object, required for all Advanced Object Labeling services.
timelapses	Dictionary keyed by the type of timelapse (e.g. non_motion).	Object, optional.
filters	Dictionary keyed by the type of filter (e.g. video_upload).	Object, optional.
hashes	Dictionary keyed by the type of content being hashed (e.g. video).	Object, optional.

counter_quotas[:counter_name]

Name	Description	Details
limit	The integer count included as part of the base Plan.	integer, required.
overage	The integer count to purchase whenever usage exceeds the limit included in the Plan.	integer, required.
price	The float cents amount to charge for the purchase of the overage.	float, required.

rate_quotas[:service_name]

Services are rate-limited using a Token Bucket strategy. The bucket for each service is filled at an hourly_rate up to a maximum of capacity.

service_name	Description
LABEL_DETECTION	Object labeling like make and model of car.
TEXT_DETECTION	Optical Character Recognition (OCR).
FACE_DETECTION	Detection of faces without recognition.
FACE_RECOGNITION	Recognition of the detected faces.

Name	Description	Details
ii	The minimum interest score to which this service will be applied. It’s best to use the default 2 so that only important motion gets advanced object labeling.	integer, required. Default is 2.
capacity	The integer max count of tokens that this service bucket can hold.	integer, required.
hourly_rate	The integer number of tokens allocated to this service bucket each hour.	integer, required.
max_calls_per_event	The integer maximum number of times this service is called per Event. This also determines the number of high resolution croppings are extracted from each Event.	integer, required.

extraction

Name	Description	Details
fph	The frames per hour to extract from the original video when creating timelapses.	integer, required.
jpeg_quality	The value used for the ffmpeg -q:v parameter in extracting JPEGs for the timelapse.	integer, optional.

interest_scores

Value	Description
0	non-motion Events (no significant moving objects)
1	unimportant motion Events (e.g. a passing car on a distant street)
2	important motion Events (corresponds to your default “Top” search results)

hashes

There is currently only a single content type (video) and single value (SHA-1) supported for the SHA checksum hash.

Key	Value
video	SHA-1

Delete plan Metadata

curl \
    -H 'Authorization: token gKBVf2b7' \
    -X DELETE https://video.acme.com/api/plans/metadata?id=my-best-1

The response is:

204 (No Content)

HTTP Request

DELETE https://video.acme.com/api/plans/metadata

NOTE the required use of your own custom domain.

URL Parameters

Name	Description	Details
id	The id of the Metadata.	string, required.

Subscriptions

The subscriptions API endpoint is being refactored and will undergo changes soon. The concepts will remain similar, but the paths and payloads will change.

List Subscriptions

Example command is:

curl \
    -H 'Authorization: token gKBVf2b7' \
    https://video.acme.com/api/plans/subscribed?user=sarah%40example.com

Sample response is keyed by the id of the Plan:

{
    "plan_abc123": {
        "camera_ids": [
            "cc:123456:AABBCCDDEE43:AABBCCDDEE43.1",
            "cc:123456:AABBCCDDEE43:AABBCCDDEE43.2",
            "cc:123456:AABBCCDDEE62:AABBCCDDEE62.2",
            "cc:123456:AABBCCDDEE62:AABBCCDDEE62.1",
            "cc:123456:AABBCCDDEE62:AABBCCDDEE62.3",
            "cc:123456:AABBCCDDEE62:AABBCCDDEE62.0",
            "cc:123456:AABBCCDDEE43:AABBCCDDEE43.0"
        ],
        "expiration_date": "2018-09-04T18:39:29.000-0000",
        "id": "plan_abc123",
        "metadata": {
            "allowance_sum": "plan",
            "counter_quotas": {
                "events_label_detection_count": {
                    "limit": 0,
                    "overage": 1,
                    "price": 0.21
                },
                "events_text_detection_count": {
                    "limit": 0,
                    "overage": 1,
                    "price": 0.21
                },
                "timelapse_count": {
                    "limit": 0,
                    "overage": 1,
                    "price": 25.0
                },
                "uploads_size_bytes": {
                    "limit": 95850000000,
                    "overage": 9585000000,
                    "price": 49.162492501684696
                }
            },
            "description": "Minimum for per-day events_uploaded_count: 500, bitrate: 2048 kbps, events_label_detection_count: 0, events_text_detection_count: 0, video stored for 30 days, and billed each 30 days.",
            "filters": {},
            "hashes": {
                "video": "SHA-1"
            },
            "id": "resiplus500",
            "input": {
                "allowance_sum": "plan",
                "bitrate_kbps": 2048,
                "events_label_detection_count": {
                    "amount": 0,
                    "interval": "day",
                    "interval_count": 1
                },
                "events_text_detection_count": {
                    "amount": 0,
                    "interval": "day",
                    "interval_count": 1
                },
                "events_uploaded_count": {
                    "amount": 500,
                    "interval": "day",
                    "interval_count": 1
                },
                "storage_duration": {
                    "amount": 30,
                    "interval": "day",
                    "interval_count": 1
                },
                "vision_services_max_calls_per_event": 1
            },
            "storage_duration_days": 30,
            "stripe_metadata": {
                "camio_plan_metadata_id": "resiplus500",
                "camio_plan_metadata_url": "https://camio.com/api/plans/metadata/?id=resiplus500"
            },
            "timelapses": {
                "non_motion": {
                    "extraction": {
                        "extraction_fph": 3600,
                        "fph": 3600,
                        "img_size_y": 480
                    }
                },
                "on_demand": {
                    "encoding": {
                        "crf": 28,
                        "fps": 30,
                        "maxrate": "8000k"
                    },
                    "extraction": {
                        "extraction_fph": 3600,
                        "fph": 3600,
                        "jpeg_quality": 10
                    }
                }
            },
            "url": "https://camio.com/api/plans/metadata/?id=resiplus500"
        },
        "slot_count": 7,
        "stripe_subscription": {
            "billing": "charge_automatically",
            "cancelAtPeriodEnd": false,
            "created": 1528051169,
            "currentPeriodEnd": 1535999969,
            "currentPeriodStart": 1533321569,
            "customer": {
                "expandedObject": {},
                "id": "cus_Cabcxyz"
            },
            "id": "sub_xyzpdq",
            "items": {
                "data": [
                    {
                        "created": 1528051170,
                        "id": "si_fgh987",
                        "object": "subscription_item",
                        "plan": {
                            "amount": 639,
                            "created": 1528006818,
                            "currency": "usd",
                            "id": "plan_abc123",
                            "interval": "month",
                            "intervalCount": 1,
                            "livemode": true,
                            "metadata": {
                                "camio_plan_metadata_id": "resiplus500"
                            },
                            "name": "Residential 500",
                            "object": "plan"
                        },
                        "quantity": 7
                    }
                ],
                "hasMore": false,
                "totalCount": 1,
                "url": "/v1/subscription_items?subscription=sub_xyzpdq"
            },
            "metadata": {
                "server_name": "camio.com",
                "userid": "cc:123456"
            },
            "object": "subscription",
            "plan": {
                "amount": 639,
                "created": 1528006818,
                "currency": "usd",
                "id": "plan_abc123",
                "interval": "month",
                "intervalCount": 1,
                "livemode": true,
                "metadata": {
                    "camio_plan_metadata_id": "resiplus500"
                },
                "name": "Residential 500",
                "object": "plan"
            },
            "quantity": 7,
            "start": 1528051169,
            "status": "active"
        },
        "subscription_id": "sub_xyzpdq"
    }
}

This retrieves the plans to which the user is subscribed.

HTTP Request

GET https://video.acme.com/api/plans/subscribed

URL Parameters

Name	Description	Details
user	The email address of the user.	string, optional.

Create a Subscription

Example request is:

curl \
    -H "Authorization: token xyzauthtoken" \
    -d '{"user":{"email":"sarah@example.com"}, "num_cameras": 7, "plan": "plan_abc123"}'
    -X POST https://video.acme.com/api/users/me/stripe/subscription

The response is:

204 (No Content)

Since a Stripe payment token is required to create new subscriptions, this API works only after the payor has created a Stripe Customer object by providing payment credentials on the account page.

NOTE the required use of your own custom domain (i.e. video.acme.com rather than camio.com).

HTTP Request

POST https://video.acme.com/api/users/me/stripe/subscription

JSON Payload

Name	Description	Details
plan	The id of the plan.	string, required.
num_cameras	The number of camera streams subscribed to this plan.	integer, required.
user	The user object containing at least user.email.	object, optional. Defaults to signed-in user.
promotion_code	The id of the Stripe Coupon to be applied to this subscription.	string, optional.
billing	The value "charge_automatically" or "send_invoice". Invoice billing requires pre-approval of payment terms.	string, optional. Defaults to charge_automatically.

Delete a Subscription

Example command is:

curl \
    -H "Authorization: token xyzauthtoken" \
    -X DELETE https://video.acme.com/api/users/me/stripe/subscription?plan_id=plan_abc123&user=sarah%40example.com

The response is:

204 (No Content)

HTTP Request

DELETE https://video.acme.com/api/users/me/stripe/subscription

URL Parameters

Name	Description	Details
plan_id	The id of the Plan.	string, required.

Refunds

NOTE the required use of your own custom domain (i.e. video.acme.com rather than camio.com).

List refunds

Example command

curl \
    -H 'Authorization: token gKBVf2b7' \
    https://video.acme.com/api/refunds

The JSON response is:

{
  "data": [
    {
      "id": "re_1CY0LNIduGGoPD7rOAhgqJs2",
      "object": "refund",
      "amount": 2478,
      "balance_transaction": {
        "id": "txn_1CY0LNIduGGoPD7ri9UTPEJY",
        "expanded_object": null
      },
      "charge": {
        "id": "ch_1CXaaOIduGGoPD7r18cRKaLe",
        "expanded_object": null
      },
      "created": 1527809889,
      "currency": "usd",
      "description": null,
      "metadata": {},
      "reason": null,
      "receipt_number": null,
      "status": "succeeded"
    },
    {
      "id": "re_1CXzjwIduGGoPD7rdVErUrGw",
      "object": "refund",
      "amount": 80,
      "balance_transaction": {
        "id": "txn_1CXzjwIduGGoPD7rjS9Yxi03",
        "expanded_object": null
      },
      "charge": {
        "id": "ch_1CXf8XIduGGoPD7ru9RfJiAc",
        "expanded_object": null
      },
      "created": 1527807568,
      "currency": "usd",
      "description": null,
      "metadata": {},
      "reason": null,
      "receipt_number": null,
      "status": "succeeded"
    }
  ]
}

List up to 10 of the most recently refunded charges.

HTTP Request

GET https://video.acme.com/api/refunds

Create a refund

Example command

curl \
    -H 'Authorization: token gKBVf2b7' \
    -d '{"charge": "ch_1CY1f7IduGGoPD7rL51Pvigk"}' \
    -X PUT https://video.acme.com/api/refunds

JSON response is:

{
  "id": "re_1CY1y0IduGGoPD7rwczgDRr4",
  "object": "refund",
  "amount": 2478,
  "balance_transaction": {
    "id": "txn_1CY1y0IduGGoPD7rCphJYj1X",
    "expanded_object": null
  },
  "charge": {
    "id": "ch_1CY1f7IduGGoPD7rL51Pvigk",
    "expanded_object": null
  },
  "created": 1527816128,
  "currency": "usd",
  "description": null,
  "metadata": {},
  "reason": null,
  "receipt_number": null,
  "status": "succeeded"
}

Refund the specific charge in full. You must use this API, instead of the Stripe Dashboard, to refund the application_fee that was paid to Camio.

HTTP Request

PUT https://video.acme.com/api/refunds

JSON Payload

Name	Description	Details
charge	The id of the Stripe charge.	string, required.

Users

Create a User

Example command

curl \
    -H 'Authorization: token gKBVf2b7' \
    -d '{"email": "jane@doe.com", "first_name": "Jane", "login_type":"oauth", "password": "JaneRocks"}' \
    -X PUT https://camio.com/api/users

Formatted input:

{
    "email": "jane@doe.com",
    "first_name": "Jane",
    "login_type": "oauth",
    "password": "JaneRocks"
}

Response from successful creation is 200 with JSON:

{
    "user_id": "cc:5086303379676187200278",
    "email": "jane@doe.com"
}

Response when user already existed is 400 with JSON:

{
    "name":"EMAIL_ADDRESS_IN_USE",
    "message":"jane@doe.com is already in use with a Camio account. Please sign in with Email."
}

The creation of new users is currently restricted to whitelisted partners. In addition:

1. The email address of the new user must be of the same domain as the authenticated user. For example, admin@acme.com can create users dallas@acme.com and houston@acme.com but not bob@example.com, because example.com isn’t the same domain as acme.com.
2. The email address of the authenticated user must have been verified.

HTTP Request

PUT https://camio.com/api/users

JSON Payload

Name	Description	Details
first_name	First name.	string, required.
last_name	Last name.	string, optional.
email	Email address.	string, required.
password	Password with minimum length of 6 characters.	string, required.
login_type	oauth	string, required.

Get a User

Example command is:

curl \
    - H "Authorization: token abc123xyz" \
    https://camio.com/api/users/jane%40doe.com

The 200 response JSON is:

{
    "user_id": "1175XXXX677",
    "email": "jane@doe.com"
}

HTTP Request

GET https://camio.com/api/users/:user

URL Parameters

Name	Description	Details
user	The URI encoded email address or user_id of the user being looked up. You can also use me for the currently authenticated user instead.	string, optional, e.g. jane%40host.com.

Accounts

Please use the Users endpoint instead. This endpoint will become focused on billing-related information only.

Get an Account

Example command is:

curl \
    - H "Authorization: token abc123xyz" \
    https://camio.com/api/accounts/?user=test%40example.com

JSON response is:

{
    "user_id": "1175XXXX677",
    "message": "Purchase more cameras",
    "plans": []
}

Describes the account associated with the user.

To get the full response inclusive of plans and message, the authenticated user must have “Can Manage” permission for the user‘s account. Otherwise, only the user_id is included in the response for the convenience of validating the existence of the account.

HTTP Request

GET https://camio.com/api/accounts

URL Parameters

Name	Description	Details
user	The email address of the account owner (host).	string, optional, e.g. “jane@host.com”. Omit to lookup the currently authenticated user.

List User’s Accounts

Example command is:

curl \
    - H "Authorization: token abc123xyz" \
    https://camio.com/api/users/jane@host.com/accounts

JSON response is:

[
    {
        "ip_address": "73.170.187.19",
        "user_email": "jane@host.com",
        "user_id": "1175XXXX677"
    }
]

Lists the accounts associated with the user. Currently, each user has only a single account.

The ip_address in the response is DEPRECATED and is the IP address of the API caller rather than of the user account.

HTTP Request

GET https://camio.com/api/users/:user/accounts

URL Parameters

Name	Description	Details
user	The email address of the account owner (host).	string, required, e.g. “jane@host.com” or “me” for currently authenticated user.

Guests

List Guests

Example command is:

curl \
    - H "Authorization: token abc123xyz" \
    https://camio.com/api/users/jane@host.com/guests

JSON response is:

[
    {
        "guest": {
            "email": "carter@maslan.com",
            "email_info": {
                "email_address": "carter@maslan.com",
                "is_default": true,
                "is_verified": true
            },
            "user_id": "fb:1107701"
        },
        "host": {
            "email": "jane@host.com",
            "user_id": "1175XXXX677"
        },
        "permissions": [
            "SEE_CONTENT_ALL",
            "SEE_ALERT_LABEL_MATCH",
            "CREATE_CAMIOS"
        ]
    },
    {
        "guest": {
            "email": "john@guest.com",
            "email_info": {
                "email_address": "john@guest.com",
                "is_default": true,
                "is_verified": true
            },
            "user_id": "1090107XXXXX218614620"
        },
        "host": {
            "email": "jane@host.com",
            "user_id": "1175XXXX677"
        },
        "permissions": [
            "SEE_CONTENT_ALL",
            "SEE_ALERT_LABEL_MATCH",
            "CREATE_CAMIOS"
        ]
    },
]

Lists the Guests of the user.

HTTP Request

GET https://camio.com/api/users/:user/guests

URL Parameters

Name	Description	Details
user	The email address of the account owner (host).	string, required, e.g. “jane@host.com” or “me” for currently authenticated user.

Create a Guest

Example command is:

curl \
    -H 'Authorization: token gKBVf2b7' \
    -H "Content-Type: application/json" \
    -d '{...}'
    -X PUT https://camio.com/api/users/jane@host.com/guests

The JSON payload for the PUT -d above is like:

{
    "guest": {
        "email": "john@guest.com"
    },
    "host": {
        "email": "jane@host.com",
        "user_id": "105730904519723370437"
    },
    "permissions": [
        "SEE_CONTENT_ALL",
        "SEE_ALERT_LABEL_MATCH",
        "CREATE_CAMIOS",
        "ADMINISTER_ACCOUNT"
    ]
}

JSON Response is:

{
    "guest": {
        "email": "john@guest.com",
        "email_info": {
            "email_address": "john@guest.com",
            "is_default": true,
            "is_verified": true
        },
        "user_id": "117550000798386757677"
    },
    "host": {
        "email": "jane@host.com",
        "user_id": "105730904519723370437"
    },
    "permissions": [
        "SEE_CONTENT_ALL",
        "SEE_ALERT_LABEL_MATCH",
        "CREATE_CAMIOS",
        "ADMINISTER_ACCOUNT"
    ]
}

HTTP Request

PUT https://camio.com/api/users/:user/guests

URL Parameters

Name	Description	Details
user	The email address of the account owner (host).	string, required, e.g. “jane@host.com” or “me” for currently authenticated user.

JSON Payload

Name	Description	Details
guest	The guest User object with email.	Object, required.
host	The account owner User object with email and user_id.	Object, required.
permissions	The list of permissions among SEE_CONTENT_ALL, SEE_ALERT_LABEL_MATCH, CREATE_CAMIOS, ADMINISTER_ACCOUNT	List, required.

Delete a Guest

Example command is:

curl \
    -H "Authorization: token xyz123abc" \
    -X DELETE https://camio.com/api/users/jane@host.com/guests/john@guest.com/?authorizations=SEE_CONTENT_ALL,SEE_ALERT_LABEL_MATCH,CREATE_CAMIOS

Response is

204 (No Content)

HTTP Request

DELETE https://camio.com/api/users/:user/guests/:guest/?authorizations=:auths_csv

URL Parameters

Name	Description	Details
user	The email address of the account owner (host).	string, required, e.g. “jane@host.com” or “me” for currently authenticated user.
guest	The email address of the Guest.	string, required, e.g. “john@guest.com”.
auths_csv	Comma-separate list of permissions to DELETE.	string, required. e.g. “SEE_CONTENT_ALL,SEE_ALERT_LABEL_MATCH,CREATE_CAMIOS”.

Hosts

List Hosts

Example command is:

curl \
    - H "Authorization: token abc123xyz" \
    https://camio.com/api/users/guest%40example.com/hosts

Response is

[
    {
        "guest": {
            "email": "guest@example.com",
            "email_address": "guest@example.com",
            "email_info": {
                "date_verified": "2018-04-25T02:36:12.857-0000",
                "is_default": true,
                "is_verified": true
            },
            "user_id": "185804764220139124118"
        },
        "host": {
            "email": "tester@camio.com",
            "user_id": "cc:5776262944889982246100"
        },
        "permissions": [
            "SEE_CONTENT_ALL",
            "SEE_ALERT_LABEL_MATCH",
            "CREATE_CAMIOS"
        ]
    }
]

HTTP Request

GET https://camio.com/api/users/:user/hosts

URL Parameters

Name	Description	Details
user	The email address of the Guest.	string, required, e.g. “guest@example.com” or “me” for currently authenticated user.

Queries

Pinned Queries are persistent searches that trigger alerts or Hooks whenever a newly arriving Event matches the query.

List Pinned Queries

Example command is:

curl \
    -H 'Authorization: token gKBVf2b7' \
    https://camio.com/api/users/me/queries/pinned

JSON Response is:

[
    {
        "id": "0b7ebfc7-ba41-4f3f-9582-f5863a30e304",
        "text": "Backyard dog 9am to 7pm jane@host.com"
    },
    {
        "id": "d8d0ecd4-bf65-4644-b405-40e2c412f757",
        "text": "people in Office 9pm to 9am jane@host.com"
    }
]

HTTP Request

GET https://camio.com/api/users/:user/queries/pinned

URL Parameters

Name	Description	Details
user	The email address of the account owner.	string, required, e.g. “jane@host.com” or “me” for currently authenticated user.

Create a Pinned Query

Example command is:

curl \
    -H 'Authorization: token gKBVf2b7' \
    -H "Content-Type: application/json" \
    -d {...} \
    https://camio.com/api/users/jane@host.com/queries/pinned

The -d JSON is like:

{
    "id": "6d83f6f0-5306-40b0-880c-a395e0c5a320",
    "text": "locked jane@host.com"
}

The 200 JSON response echos the input request:

{
    "id": "6d83f6f0-5306-40b0-880c-a395e0c5a320",
    "text": "locked jane@host.com"
}

HTTP Request

PUT https://camio.com/api/users/:user/queries/pinned

URL Parameters

Name	Description	Details
user	The email address of the account owner.	string, required, e.g. “jane@host.com” or “me” for currently authenticated user.

Deleta a Pinned Query

Example command is:

curl \
    -H "Authorization: token abc123xyz" \
    -X DELETE https://camio.com/api/users/jane@host.com/queries/pinned/6d83f6f0-5306-40b0-880c-a395e0c5a320

Response is:

204 (No Content)

HTTP Request

DELETE https://camio.com/api/users/:user/queries/pinned/:id

URL Parameters

Name	Description	Details
user	The email address of the account owner.	string, required, e.g. “jane@host.com” or “me” for currently authenticated user.
id	The id of the pinned query.	string, required, e.g. “6d83f6f0-5306-40b0-880c-a395e0c5a320”.

Domains

If your company registers its domain at camio.com/domains, then system events from all accounts of that domain can trigger callbacks to endpoints of your choosing.

Contact us to register your domain.

Get a Domain

Example command is:

curl \
    -H "Authorization: token abc123" \
    https://camio.com/api/domains/acme.com

Response JSON:

{
    "date_updated": "2019-03-20T22:26:33.933-0000",
    "endpoints": {
        "https://acme.com/camio/allcallbacks": {
            "event_types": []
        },
        "https://acme.com/camio/errors": {
            "event_types": [
                "incident.created"
            ]
        }
    },
    "members": [
        {
            "role": "admin",
            "user": {
                "email": "jane@acme.com"
            }
        }
    ],
    "name": "acme.com"
}

HTTP Request

GET https://camio.com/api/domains/:domain

URL Parameters

Name	Description	Details
domain	The name of the domain itself.	string, required, e.g. “acme.com”.

Create a Domain

Example command:

curl \
    -H "Content-Type: application/json" \
    -H "Authorization: token abc123" \
    -d '{...see below...}' \
    -X PUT https://camio.com/api/domains

Sample input payload for the “acme.com” domain:

{
    "endpoints": {
        "https://acme.com/camio/allcallbacks": {
            "event_types": []
        },
        "https://acme.com/camio/errors": {
            "event_types": [
                "incident.created"
            ]
        }
    },
    "members": [
        {
            "role": "admin",
            "user": {
                "email": "jane@acme.com"
            }
        }
    ],
    "name": "acme.com"
}

Currently, only support@camio.com can create new domain registrations with PUT. After the domain has been created, then your designated admin member can POST to update the domain.

HTTP Request

PUT https://camio.com/api/domains

Name	Description	Details
endpoints	Map keyed by URL of the Endpoints that will receive callbacks. If no event_types are listed, then the URL will receive callbacks on all events.	Object keyed by URL, required.
members	List of people authorized to update the domain.	List, required unless performed by support@camio.com.
name	The name of the domain.	String, required. e.g. acme.com.

event_types

Name	Description
camera.created	Camera has been created.
camera.updated	Camera has been renamed or otherwise changed.
camera.deleted	Camera has been deleted.
device.deleted	Box has been deleted.
incident.created	Error counter has been created (incremented).
zone.created	Zone has been created.

Update a Domain

Example command:

curl \
    -H "Content-Type: application/json" \
    -H "Authorization: token abc123" \
    -d '{...see below...}' \
    -X POST https://camio.com/api/domains/acme.com

Sample input payload for the “acme.com” domain:

{
    "endpoints": {
        "https://acme.com/camio/allcallbacks": {
            "event_types": []
        },
        "https://acme.com/camio/errors": {
            "event_types": [
                "incident.created",
                "device.deleted"
            ]
        }
    },
    "members": [
        {
            "role": "admin",
            "user": {
                "email": "joe@acme.com"
            }
        }
    ],
    "name": "acme.com"
}

The most common update is to add or remove endpoints receiving callbacks.

The POST acts as a PATCH in extending the endpoints or members. So a POST with a single item in the endpoints list, for example, will add that endpoint to the list of existing endpoints.

If you want to remove all endpoints, then POST with an empty list like "endpoints":[]. The empty list is interpreted as intent to delete all items in the list.

HTTP Request

POST https://camio.com/api/domains/:domain

The input payload is the same as used to Create a Domain.

Name	Description	Details
domain	The name of the domain itself.	string, required, e.g. “acme.com”.

Delete a Domain

Currently, only support@camio.com can delete domains.

HTTP Request

DELETE https://camio.com/api/domains/:domain

Name	Description	Details
domain	The name of the domain itself.	string, required, e.g. “acme.com”.

Event Callbacks

camera.updated

{
  "id": "292f4560-27c2-4f7b-8280-e4dde99d7e51",
  "type": "camera.updated",
  "data": {
    "object": {
      "camera": {
        "name": "Front",
        "tags": [],
        "camera_id": "117550000798386757677:7CDD9060A16B:7CDD9060A16B.0",
        "user_agent": "CamioBox (Linux; rpi3) Firmware:box-rpi3-cam.201712100117-a9317ccaaf78af402eb9bab40b0b22619771ac7e"
      },
      "user": {
        "user_id": "117550000798386757677",
        "email": "jcmaslan@gmail.com"
      }
    },
    "previous_attributes": {
      "name": "Front Old Name"
    }
  }
}

incident.created

{
  "id": "1856192a-3bfc-4d36-85a4-8f037947d123",
  "type": "incident.created",
  "data": {
    "object": {
      "user": {
        "user_id": "109010722686218614620",
        "email": "john@camiolog.com",
      },
      "incident": {
        "type": "incident",
        "counter_events": {
          "segmentation_process_restart_count": {
            "counter": "segmentation_process_restart_count",
            "value": 25,
            "description": "25 \u003e 0 means the network connection to the video stream is unstable have restarted 25 times in 15 minutes."
          }
        },
        "camera_name": "office-camera",
        "date": "2019-03-20T22:06:22.170-0000"
      }
    }
  }
}

zone.created

{
  "id": "eb5c4b42-1697-4e42-bfd4-f8e3d5020bee",
  "type": "zone.created",
  "data": {
    "object": {
      "zone": {
        "polygons": [
          {
            "points": [
              {
                "x": 3.289473684210526E-4,
                "y": 0.4400749063670412
              },
              {
                "x": 0.3424342105263158,
                "y": 0.4307116104868914
              },
              {
                "x": 0.8529605263157894,
                "y": 0.99812734082397
              },
              {
                "x": 0.0024342105263157896,
                "y": 0.9925093632958801
              },
              {
                "x": 3.289473684210526E-4,
                "y": 0.4400749063670412
              }
            ]
          }
        ],
        "name": "Entrance"
      },
      "user": {
        "user_id": "117550000798386757677",
        "email": "jcmaslan@gmail.com"
      },
      "request_user": {
        "user_id": "117550000798386757677",
        "email": "jcmaslan@gmail.com"
      },
      "request_wan_ip_address": "73.170.187.19"
    }
  }
}

After you update your domain to specify one or more endpoints, you’ll receive a JSON payload that varies by the type of the event.

The examples on the right show callback payloads for the event_types:

1. camera.updated
2. incident.created
3. zone.updated

Notice that the camera.updated examples shows the use of previous_attributes to convey what changed. In this case, the camera was renamed from “Front Old Name” to “Front”.

Also, the incident.created callback correlates to the data you can retrieve with Incident Counters.

Sites

List Sites

Example command is:

curl \
    -H 'Authorization: token gKBVf2b7' \
    https://camio.com/api/sites

JSON response is like:

[
    {
        "date_updated": "2017-09-29T03:58:23.749-0000",
        "members": {
            "cc:49148629": [
                {
                    "date_granted": "2017-09-29T03:58:23.748-0000",
                    "role": "admin"
                }
            ]
        },
        "server_name": "video.acme.com",
        "stripe_user_id": "acct_1ApXXYYZZq9Ci3"
    }
]

List any Site with the authenticated user among its members.

HTTP Request

GET https://camio.com/api/sites

Get a Site

Example command to get site id video.acme.com:

curl \
    -H 'Authorization: token gKBVf2b7' \
    https://camio.com/api/sites/video.acme.com

JSON response is like:

{
    "date_updated": "2017-09-29T03:58:23.749-0000",
    "members": {
        "cc:49148629": [
            {
                "date_granted": "2017-09-29T03:58:23.748-0000",
                "role": "admin"
            }
        ]
    },
    "server_name": "video.acme.com",
    "stripe_user_id": "acct_1ApXXYYZZq9Ci3"
}

Get a single Site by its id, which is its server_name.

HTTP Request

GET https://camio.com/api/sites/:site_id

URL Parameters

Name	Description	Details
site_id	The server name of the Site.	string, required, e.g. “video.acme.com”

Create a Site

Example command, where the data is JSON explained below:

curl \
    -H 'Authorization: token gKBVf2b7' \
    -H "Content-Type: application/json" \
    -d '{...}'
    -X PUT https://camio.com/api/sites

The JSON payload for the PUT -d above is like:

{
    "members": {
        "cc:49148629": [
            {
                "date_granted": "2017-09-29T03:58:23.748-0000",
                "role": "admin"
            }
        ]
    },
    "server_name": "video.acme.com",
    "stripe_user_id": "acct_1ApXXYYZZq9Ci3"
}

The response is 200 with JSON Site and date_updated:

{
    "date_updated": "2018-08-23T04:45:22.356-0000",
    "members": {
        "cc:49148629": [
            {
                "date_granted": "2017-09-29T03:58:23.748-0000",
                "role": "admin"
            }
        ]
    },
    "server_name": "video.acme.com",
    "stripe_user_id": "acct_1ApXXYYZZq9Ci3"
}

Only Camio administrators can create a Site via API. Partners should instead create their site via the OAuth connection to their Stripe Account.

HTTP Request

PUT https://camio.com/api/sites/

Delete a Site

Example command is:

curl \
    -H 'Authorization: token gKBVf2b7' \
    -X DELETE https://camio.com/api/sites/video.acme.com

The response is:

204 (No Content)

Only Site administrators can delete a Site.

HTTP Request

DELETE https://camio.com/api/sites/:site_id

URL Parameters

Name	Description	Details
site_id	The server name of the Site.	string, required, e.g. “video.acme.com”

Errors

The Camio API uses standard HTTP status codes.