Welcome

The Camio API makes it simple to add smart video monitoring to other services, cameras, and sites. This documentation is for select partners, so please let us know of any problems you find with either this documentation or the Camio API itself.

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-0000

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:

when the camera front sees important motion, and
the moving object is labeled people approaching mailbox blue, then
execute HTTP POST http://example.com/camio/package-delivery with the json payload describing the triggering event.

Seeing Recorded Content

<iframe src="https://www.camio.com/?v=b1bqks3l76yo&key=123abc" width="640" height="480" 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

# 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"

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

You must replace OAUTH-TOKEN with your API 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

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

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

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

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

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

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

{
    "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

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

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

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:

when the camera front or gate sees important motion, and
the event is labeled people approaching mailbox, then
execute HTTP POST http://example.com/camio/package-delivery

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

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”

{
  "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:

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.

Delete Hook

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

200 (OK)
Content-Type: application/json

{
    "query": {
        "date": "2014-02-21T04:52:20.911-0000",
        "sort": "desc",
        "motion_type": "imo",
        "object_type": "events",
        "content_type": "image"
    },
    "result": {
        "bucket_type": "event",
        "buckets": [
            {
                "bucket_id": "EagxzfmNhbW...olNakCQw",
                "source": "frontDoor",
                "labels": [
                    "walkway",
                    ...
                ],
                "earliest_date": "2014-02-21T04:12:38.911-0000",
                "latest_date": "2014-02-21T04:12:48.142-0000",
                "max_interest_level": 2,
                "cover_image_id": "agxzfmNhbW...olNakCQw",
                "annotations": [
                            {
                                "object_id": "agxzfmNhbW...olNakCQw",
                                "type": "s"
                            }
                        ],
                "images": [
                    {
                        "id": "agxzfmNhbW...olNakCQw",
                        "content_type": "image/jpeg",
                        "date_created": "2014-02-21T04:12:38.911-0000",
                        "labels": [
                            "walkway",
                            ...
                        ],
                        "interest_level": 2,
                        "interest_score": 0.65,
                        "image_bytes": "/9j/4AAQSkZJ...AAQ",
                        "access_token": "AQC18TKq...5k9H8w"
                    },
                    ...
                ],
                "count": 5
            },
            ...
        ],
        "count": 30,
        "more_results": true,
        "earliest_date_considered": "2014-02-21T04:12:38.911-0000",
        "latest_date_considered": "2014-02-21T04:23:00.111-0000"
    }
}

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

Name	Description	Details
object_type	The type of object to search for.	string, optional, supported values: (`events`, `seconds`, `hours`, `camios`), default: `events`
date	Filter date in ISO8601 format.	string, optional, example: `2014-03-13T11:27:40.929-0000`
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: `ag1zfmNhbWlvbG9nZ2VyckMLEgVFdmVudCI4ZXY6MTAzOTQ0OTExOTgxNzY0MDIyMTQzOndlc3Q6MjAxNC0xMS0xOVQyMzoyNzowNy44OTQwMDAM`
sort	The result sort order.	string, optional, supported values: (`asc`, `desc`), default: `desc`
sources	Comma separated list of camera sources.	string, optional, example: `Front`
labels	Comma seperated list of labels.	string, optional, example: `Walkway`
event	Single Event id to be used as the paragon for similarity search.	string. optional, used only for similarity search.
content_type	The type of content to fetch.	string, optional, supported values: (`image`, `video`), default: `image`
motion_type	The minimum importance of motion to inlucude in the results. Options include all motion, signification motion only, important motion only and labeled motion only in increasing levels of importance filtering.	string, optional, supported values: (`all`, `smo`, `imo`, `lmo`), default: `imo`
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`
user	The email address of the host account that the search should be performed upon.	string, optional, example: `test@example.com`
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.
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`
sxs	Camio INTERNAL ONLY. The side by side tag to search for.	string, optional, example: `special`

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

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"

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 at the following endpoint:

HTTP Request

POST 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.

For content uploads, both HTTP POST and PUT are supported.

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 and `h` for heartbeat uploads.	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`

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

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

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

{
    "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.

With all POSTs that contain a JSON body it’s important to check that the request content-type is application/json or text/plain rather than application/x-www-form-urlencoded.

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

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

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

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.

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`

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.

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.

POST/PUT/PATCH all behave as a PATCH. That is, the json payload does NOT replace the user’s setting wholesale but rather updates only the attributes supplied in the json

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

400 (Bad Request)
Content-Type: application/json

 {"message":"Invalid request"}

The Camio API uses the following error codes:

Error Code	Meaning
400	Bad Request
401	Unauthorized – Your API key is invalid
404	Not Found – The specified resource could not be found
429	Too Many Requests – You’ve hit a rate limit
500	Internal Server Error – We had a problem with our server. Try again later.