NAV

Welcome

The Camio API makes it simple to add smart video monitoring to other services, cameras, and sites. 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://www.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

curl \
-H "Content-Type: video/mp4" \
-X PUT \
-T "2014-07-21T20:38:31.000-07:00.mp4" \
https://www.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://www.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 tablet, smartphone, computer or IP 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.

Registering Callbacks

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

Hooks enable you to take an action when there is important motion or sound detected. The condition that triggers the hook’s callback For example, use the command on the right to create a hook requesting that:

Seeing Recorded Content

<iframe src="https://www.camio.com/?v=b1bqks3l76yo&key=123abc" width="603" height="452" frameBorder="0"></iframe>

Anyone can use the free Camio Browser, iOS, and Android apps to view recorded content. But if you’d like to embed content on your site, you can use an iframe as in this example of the mischievous dog Kody:

URL Parameters

Name Description Details
v 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

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://www.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. The API is currently in private BETA. You can obtain a development OAuth token by using the Generate button at https://www.camio.com/settings/integrations/#api. An application registration page and an OAuth registration endpoint will be provided in the near future to allow you to request OAuth tokens for users of your application.

Authorization Header

Camio expects the token to be included in all API requests to the server in a header that looks like the following:

Authorization: token OAUTH-TOKEN

Authorization Parameter

Alternatively, the OAuth token can be set as a access_token query parameter.

https://www.camio.com/api/search/?access_token=OAUTH-TOKEN

The use of the Authorization header is the preferred method of authentication with an OAuth token.

How to obtain and OAuth Token

Redirect users to request Camio access

GET https://www.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://www.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://www.camio.com/api/users/me/cameras

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

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.

Cameras

List all Cameras

The JSON response is:

200 (OK)
Content-Type: application/json
[
    {
        "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 connected to an account.

HTTP Request

GET https://www.camio.com/api/users/:token/cameras/

URL Parameters

Name Description Details
token The token me for the current user. string, required, example: me

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 Camera

The JSON response is:

200 (OK)
Content-Type: application/json
{
    "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://www.camio.com/api/users/:token/cameras/:camera

URL Parameters

Name Description Details
token The token me for the current user. string, required, example: me
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.

Delete Camera

The response is:

204 (No Content)

HTTP Request

DELETE https://www.camio.com/api/users/:token/cameras/:camera

URL Parameters

Name Description Details
token The token me for the current user. string, required, example: me
camera The name of the camera. string, required, example: front

Get Camera Configuration

This request informs camio.com that there is a camera available to be claimed and/or configured by a user. Even after the camera has been claimed and configured intially, it continues to make these requests periodically (e.g. every 30 seconds, perform a GET request https://www.camio.com/api/cameras/12:34:56:78:90:12?ip_address_local=192.168.1.51&maker=Sharx&model=SCNC3904) to confirm its connection to camio.com and to check for new commands.

The response includes a list of configuration commands to be applied to the firmware settings of the camera. The path specifies the CGI command to be called using the specified method. For example, the time command in this example should result in an authenticated HTTP GET like: GET /form/setNtp?ENABLE=1&SERVER=time.nist.gov

The JSON response is:

200 (OK)
Content-Type: application/json
{
    "commands": [
        {
            "date_updated": "2015-09-19T21:43:55.794-0000",
            "id": "ping",
            "is_auth_required": true,
            "method": "GET",
            "path": "/form/setHttpPeriodSending/?ENABLE=1&SCHED=0&SCHEDID=1&HOUR=0&MIN=0&SEC=30&URL=www.camio.com/api/cameras/$(hwaddr)/?maker=Sharx&ip_address_local=$(localip)&AUTH=0&USERNAME=&PASSWORD=",
            "regex_response": "000 Success"
        },
        {
            "date_updated": "2015-09-19T21:43:55.794-0000",
            "id": "time",
            "is_auth_required": true,
            "method": "GET",
            "path": "/form/setNtp?ENABLE=1&SERVER=time.nist.gov",
            "regex_response": "000 Success"
        },
        {
            "date_updated": "2015-09-19T21:43:55.835-0000",
            "id": "ftpAlarm",
            "is_auth_required": true,
            "method": "GET",
            "path": "/form/setFtpAlarmSending/?ENABLE=1&SCHED=0&SCHEDID=1&STREAMID=0&DURATION=1&FRAMERATE=1&INTERVAL=0&SERVER=ftp.camio.com&PORT=21&REMOTEPATH=123456789012&AUTH=1&USERNAME=abc123pdq&PASSWORD=camio",
            "regex_response": "000 Success"
        }
    ],
    "ip_address": "2601:646:c401:7902:8d45:b8eb:8b40:fa84",
    "mac_address": "123456789012",
    "maker": "Sharx",
    "model": "SCNC3904",
    "user_agent": "Wget"
}

HTTP Request

GET https://www.camio.com/api/cameras/:mac_address

POST https://www.camio.com/api/cameras/:mac_address

PUT https://www.camio.com/api/cameras/:mac_address

URL Parameters

Name Description Details
mac_address The MAC address of the camera string, required, example: 12:34:56:78:90:12 or 123456789012
ip_address_local The local IP address of the camera string, optional, example: 192.168.1.51
maker The unique id of the camera maker string, required, example: Sharx
model The unique model id of the camera string, required, example: SCNC3904

Zones

List all Zones

The JSON response is:

200 (OK)
Content-Type: application/json
[
  {
    "name": "door",
    "polygons": [
      {
        "points": [
          {
            "x": 0.12079093470323,
            "y": 0.16636921918746
          },
          ...
        ]
      }
    ]
  },
  {
    "name": "entrance",
    "polygons": [
      {
        "points": [
          {
            "x": 0.45530391629449,
            "y": 0.1171216887084
          },
          ...
        ]
      }
    ]
  }
]

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

HTTP Request

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

URL Parameters

Name Description Details
token The token me for the current user. string, required, example: me
camera The name of the camera. string, required, example: front

Get Specific Zone

The JSON response is:

200 (OK)
Content-Type: application/json
{
    "name": "door",
    "polygons": [
      {
        "points": [
          {
            "x": 0.12079093470323,
            "y": 0.16636921918746
          },
          ...
        ]
      }
    ]
}

HTTP Request

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

URL Parameters

Name Description Details
token The token me for the current user. string, required, example: me
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://www.camio.com/api/users/:token/cameras/:camera/zones/:zone

URL Parameters

Name Description Details
token The token me for the current user. string, required, example: me
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://www.camio.com/api/users/:token/cameras/:camera/zones/:zone

URL Parameters

Name Description Details
token The token me for the current user. string, required, example: me
camera The name of the camera. string, required, example: front
zone The name of the zone. string, required, example: door

Hooks

Hooks enable services to be notified of events observed by Camio. Currently, the only type of trigger for hooks is label_hit. The labels include zone name, direction of movment (approaching or departing), and color (red, pink, brown, orange, yellow, green, cyan, blue, purple, magenta, white, gray, black).

List all Hooks

The JSON response is:

200 (OK)
Content-Type: application/json
[
  {
    "id": "1",
    "type": "label_hit",
    "callback_url": "https://example.com/camio/delivery",
    "query": "front people approaching mailbox"
  },
  {
    "id": "2",
    "type": "label_hit",
    "callback_url": "https://example.com/camio/dog-walker",
    "query": "kitchen dogbed leash rack"
  }
]

HTTP Request

GET https://www.camio.com/api/users/:token/hooks

URL Parameters

Name Description Details
token The token me for the current user. string, required, example: me

Get Specific Hook

The JSON response is:

200 (OK)
Content-Type: application/json
{
  "id": "1",
  "type": "label_hit",  
  "callback_url": "https://example.com/camio/delivery",
  "query": "front people approaching mailbox"
}

HTTP Request

GET https://www.camio.com/api/users/:token/hooks/:hook

URL Parameters

Name Description Details
token The token me for the current user. string, required, example: me
hook The id of the Hook string, required, example: 1

Create a Hook

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

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

The json payload included in the POST describes the event that triggered the callback.

The JSON response is:

200 (OK)
Content-Type: application/json
{
  "id": "1",
  "type": "label_hit",
  "callback_url": "https://example.com/camio/package-delivery",
  "query": "front gate people approaching mailbox"
}

HTTP Request

POST https://www.camio.com/api/users/:token/hooks

URL Parameters

Name Description Details
token The token me for the current user. string, required, example: me
type The type of event that triggers the hook’s callback. string, required, example: label_hit
camera_name Name of a particular camera (will be replaced by query later) string, optional, example: “front”
callback_url The URL that receives the POST to process the callback payload string, required, example: https://example.com/camio/package-delivery
query The query whose conditions must be matched in order to trigger the hook callback. string, required, example: “front people approaching walkway blue”

The callback JSON payload 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"]
  }
}

Callback Payload

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

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.

Delete Hook

The response is:

204 (No Content)

HTTP Request

DELETE https://www.camio.com/api/users/:token/hooks/:hook

URL Parameters

Name Description Details
token The token me for the current user. string, required, example: me
hook The id of the hook. string, required, example: 1

Search

An example request is:

GET https://www.camio.com/api/search/?text=people+approaching+outdoor+walkway+7am+yesterday+in+shades&num_results=50

The JSON response is:

200 (OK)
Content-Type: application/json
{
    "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": "in shades",
        "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",
                "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 through content by camera, date, zone, color, direction of movement, and other labels.

HTTP Request

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

Query Parameters

These query string parameters for the GET request are a subset of those supplied in the query object response. So the additional fields in the json response are in the second tablet below.

Name Description Details
text The query string text that will be parsed to populate the Query object string, optional but preferred method of searching that obviates the other fields below.
sources Comma separated list of camera sources. string, optional, example: Front,Back
labels Comma seperated list of labels. string, optional, example: Walkway
user The email address of the host account that the search should be performed upon. string, optional, example: test@example.com
content_type The type of content to fetch. string, optional, supported values: (image, video), default: image
object_type The type of object to search for. string, optional, supported values: (events, seconds, hours, camios), default: events
motion_type The minimum importance of motion to inlucude in the results. Options include all motion, labeled motion only. string, optional, supported values: (all, lmo), default: lmo
date Filter date in ISO8601 format. string, optional, example: 2014-03-13T11:27:40.929-0000
sort The result sort order. string, optional, supported values: (asc, desc), default: desc
sxs Camio INTERNAL ONLY. The side by side tag to search for. string, optional, example: special
num_results The number of events or images to return. Known issue: videos count against the number fetched but not displayed in the response. int, optional, default: 10, max: 100
view_tokens The comma-separated list of Camio tokens authorizing the search even if the user is not signed-in or not a guest. When this parameter is specified, each result includes an access_token that authorizes the subsequent fetch of each content item. string, optional - only for searching within shared Camios.
event_as_date The id of the event from which to extract the start date to be used as the date value for the search. Use event_as_date when you want to search for content using the date of a particular rather than using the date parameter. string, optional, example: ag1zfmNhbWlvbG9n44OTQwMDAM
event Single Event id to be used as the paragon for similarity search. string. optional, used only for similarity search.
fetch_motion_boxes Should motion boxes be returned. boolean, optional, supported values: (true, false), default: false
fetch_cover_thumbnails Should cover thumbnails be returned. boolean, optional, supported values: (true, false), default: false
fetch_all_thumbnails Should all thumbnails be retured. boolean, optional, supported values: (true, false), default: false
fetch_access_tokens Should thumbnails access tokens be included in the response. boolean, optional, supported values: (true, false), default: false
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

Additional Query object fields

The response from a /search adds additional fields to the Query object based on having parsed the 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.

Content

Get Content (authenticated)

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

HTTP Request

GET https://www.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)

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://www.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 Latest Live Image

The latest available live image can be retrieved from a specific camera.

HTTP Request

GET https://www.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.

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://www.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 can be used to upload an MP4:

curl -H "Content-Type:video/mp4" \
    -X POST \
    -T "filename.mp4" \
    "https://www.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://www.camio.com/api/users/51r6kndapc/cameras/front/content/2014-07-21T20:38:32.183-07:00.jpeg?camera_id=1234"

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://www.camio.com/api/users/:token/cameras/:camera/content/:name

or

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

Get your :token from camio.com/settings/tech/#techInfo. That page also includes instructions for uploading via HTTP, FTP, and Email.

URL Parameters

Name Description Details
token The token me for the current user or an upload token. string, required, example: me
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://www.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:

200 (OK)
Content-Type: application/json
{
    "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.

User Camios

A Camio is a portion of your content that can be shared by 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.

List all Camios

The JSON response is:

200 (OK)
Content-Type: application/json
[
    {
        "view_token" : "AQCLFtnBEZ...aJ5ZxTUhMPw4",
        "name" : "My Camio",
        "date_created" : "2014-02-21T04:12:38.911-0000",
        "type": "public"
    }
]

HTTP Request

GET https://www.camio.com/api/users/:token/camios

URL Parameters

Name Description Details
token The token me for the current user. string, required, example: me

Create Camio

An example of the body of the JSON request is:

{
    "name":"My Camio",
    "type":"public",
    "query": {
        "cameras": [],
        "labels": [],
        "events": ["IDX...YZ", "IDA...BC", "IDD...EF"]
    }
}

The JSON response is:

{
    "view_token" : "AQCLFtnBEZ...aJ5ZxTUhMPw4",
    "name" : "My Camio",
    "date_created" : "2014-02-21T04:12:38.911-0000",
    "type": "public"
}

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

HTTP Request

POST https://www.camio.com/api/users/:token/camios

URL Parameters

Name Description Details
token The token me for the current user. string, required, example: me

Input

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

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

The JSON response is:

200 (OK)
Content-Type: application/json
"AQBrSFvOPxQj2prnCh2wvocHnAbu_5szaBeFdQsktgE4Vw"

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

HTTP Request

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

Get Upload Token Hint

The JSON response is:

200 (OK)
Content-Type: application/json
{"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.

HTTP Request

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

or

POST https://www.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

Camios

This API endpoint references Camios that have already been created by a user with the /users/:token/camios endpoint.

Create Camio Download

Create a Camio download that includes all content of the Camio.

The JSON response is:

200 (OK)
Content-Type: application/json
[
    {
        "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 :token parameter can be supplied only in the URL itself (any JSON in the POST body is ignored).

HTTP Request

POST https://www.camio.com/api/camios/:token/downloads

URL Parameters

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

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://www.camio.com/api/users/:token/interactions

URL Parameters

Name Description Details
token The token me for the current user. string, required, example: me

Input

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 preferences and recording state. 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 yet supported in the API).

Get Settings

Fetch the user’s current settings.

The JSON response is:

200 (OK)
Content-Type: application/json

 {
    "notifications": {
        "motion_alerts" : {
            "state" : "ON",
            "method" : "PUSH",
            "options" : "mute street,window"
        },
        "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://www.camio.com/api/users/:token/settings

URL Parameters

Name Description Details
token The token me for the current user. string, required, example: me

Attributes

The Settings object currently has three attributes.

Name Description Details
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.

Supported types of notifications

There are currently four types of notifications.

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.

Update Settings

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

HTTP Request

POST https://www.camio.com/api/users/:token/settings

URL Parameters

Name Description Details
token The token me for the current user. string, required, example: me

Payload

Name Description Details
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 Applicable to motion_alerts only to specify any muted camera or label names. e.g. “mute driveway,street” to suppress alerts from the driveway and street zones. The empty string means all alerts are sent.

Errors

The Camio API uses standard HTTP status codes.