[NAV\\
- Welcome
- The Basics
- Recording Video and Images
- Registering Callbacks
- Seeing Recorded Content
- Authentication
- OAuth
- OAuth Scopes
- CSRF protection
- Upload Token
- Domain Admin Login
- Cameras
- List connected Cameras
- Get a connected Camera
- List Cameras
- Create Camera
- Update Camera
- Delete Camera
- Get a live stream session
- Create a live streaming session
- Delete a live streaming session
- Create a Camera Configuration Request
- Create a Thumbnail Request
- Export Cameras
- Import Cameras
- Labels
- List Camera Labels
- Add Camera Labels
- Replace Camera Labels
- Zones
- List all Zones
- Get Specific Zone
- Create or Edit Zone
- Delete Zone
- Faces
- List all Face labels
- Create a Face label
- Delete a Face label
- Delete all Face labels
- Hooks
- List all Hooks
- Get Specific Hook
- Create Hook
- Delete Hook
- Get Hook Responses
- Search
- Search Video
- Search Cameras
- Content
- Get Content (authenticated)
- Get Content (with access\_token)
- Get Croppings Content
- Get Latest Live Image
- Upload Content
- Upload Content (Cloud)
- Jobs
- List all Jobs
- Get Specific Job
- Create Job
- Delete Job
- Camios
- List all Camios
- Get a Camio
- Create Camio
- Update a Camio
- Create Camio Download
- Delete Camio
- Timelapses
- Create a Timelapse
- Upload Token
- Get Upload Token
- Get Upload Token Hint
- Readings
- Create Readings
- Annotations
- Create Annotations
- Create Annotations (without OAuth)
- Interactions
- Create an Interaction
- Settings
- Get Settings
- Get Settings (Local Camio Box)
- Update Settings
- Profile
- Get a Profile
- Create a Profile
- Data
- Event Counters
- Incident Counters
- Spreadsheets
- Commands
- Create a Command
- RTMP Camera Commands
- Required Commands
- Required QR Code Setup
- List all Commands
- Create a Command
- Delete all Commands
- Devices
- List all Devices
- Get a Device
- Delete a Device
- Create a Device Configuration Request
- Deprecated Device Configurations
- Plans
- List plans offered
- Create plans offered
- Delete plans offered
- List camera plans
- Get plan Metadata
- Create plan Metadata
- Delete plan Metadata
- Subscriptions
- List Subscriptions
- Create a Subscription
- Delete a Subscription
- Refunds
- List refunds
- Create a refund
- Users
- Create a User
- Get a User
- Accounts
- Get an Account
- List User’s Accounts
- Guests
- List Guests
- Create a Guest
- Delete a Guest
- Hosts
- List Hosts
- Queries
- List Pinned Queries
- Create a Pinned Query
- Deleta a Pinned Query
- Domains
- Get a Domain
- Create a Domain
- Update a Domain
- Delete a Domain
- Event Callbacks
- Sites
- List Sites
- Get a Site
- Create a Site
- Delete a Site
- Errors
- [Camio Home](/content/home/index.html)
- [Contact Us](/content/contact/index.html)
# Welcome
The [Camio](/content/site-root.html) API makes it simple to add real-time video search to any camera, NVR, VMS, website or service.
Also see [ifttt.com/camio](https://ifttt.com/camio) for ways that non-programmers can script Camio’s interaction with other services.
Please [let us know](/content/contact/index.html) 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](/content/start/index.html).
But you can also programmatically connect any other source of video/images using the [API to upload camera content](https://api.camio.com/#upload-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](/content/token/index.html) itself grants permission to upload only - without granting permission to access content.
These examples upload directly to the cloud, however [Camio Box](/content/box/index.html) 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](/content/box/vm/index.html) 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](https://api.camio.com/#hooks) enable you to take an action whenever particular events happen.
For example, use the curl command on the right to [create a hook](https://api.camio.com/#create-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](https://api.camio.com/#callback-payload) describing the triggering event.
## Seeing Recorded Content
> An example of an 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](https://api.camio.com/#search).
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:
camio.com
# camio.com is blocked
**camio.com** refused to connect.
ERR\_BLOCKED\_BY\_RESPONSE
**camio.com** refused to connect.
### HTML
``
### 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](/content/settings/integrations/#api/index.html).
### 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](/content/settings/integrations/#api/index.html).
### 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](https://api.camio.com/#oauth-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](/content/contact/index.html).
## 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](https://api.camio.com/#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](/content/token/index.html) instead (found on the page [camio.com/token](/content/token/index.html)).
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](/content/contact/index.html) 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](/content/box/index.html) 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](/content/box/register/index.html) a Camio [Box](/content/box/index.html).
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](/content/boxes/index.html) 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`](https://api.camio.com/#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](https://api.camio.com/#create-camera). 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](https://api.camio.com/#required-fields-to-identify-a-camera) 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
#### 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](https://api.camio.com/#create-camera).
## 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](https://api.camio.com/#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:
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](/content/box/index.html).
> 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](https://github.com/CamioCam/rtsp/blob/master/configs/configs.csv).
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
## 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
# 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
## Delete Zone
> The response is:
```
204 (No Content)
```
### HTTP Request
`DELETE https://camio.com/api/users/:user/cameras/:camera/zones/:zone`
### URL Parameters
# 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](https://api.camio.com/#create-a-face-label) 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](https://api.camio.com/#jobs) 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](https://api.camio.com/#callback-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
### 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](https://api.camio.com/#hook-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](https://api.camio.com/#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](https://api.camio.com/#hook-callback-payload-types) | string, required, `analysis` or `notification`. |
| mode | The optional [mode](https://api.camio.com/#hook-modes) 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](https://api.camio.com/#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](https://api.camio.com/#hook-callback-payload-types) 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](/content/hooks/index.html).
| 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](/content/contact/index.html).
## 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](https://api.camio.com/#dates-in-query-text) 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](https://api.camio.com/#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](https://api.camio.com/#get-content-authenticated).
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](https://api.camio.com/#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](https://api.camio.com/#search) response.
## 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](/content/api/content/live/east?view_tokens=41cmi5mh66m8&output=jpeg&w=320&h=180/index.html)
To create a view\_token for the latest live image of a single camera, see this [help article](http://help.camio.com/hc/en-us/articles/206543293-How-can-I-share-the-latest-live-image-publicly-).
To create the view\_token programatically with this API, [create a Camio](https://api.camio.com/#create-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](/content/box/index.html) 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×tamp=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](https://api.camio.com/#search) API or via the Camio [webapp](/content/app/index.html).
### 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](/content/boxes/index.html) 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`](https://api.camio.com/#upload-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`](https://api.camio.com/#create-job) | string, required. |
See [Job Status](https://api.camio.com/#job-status) and [Job Shard Status](https://api.camio.com/#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](https://api.camio.com/#create-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`](https://api.camio.com/#create-job). 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](https://api.camio.com/#create-hook) with the [type](https://api.camio.com/#hook-types)`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](https://blog.camio.com/camio-query-links-for-the-fastest-human-review-7179f26294db),
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](https://api.camio.com/#create-camio) 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](https://api.camio.com/#create-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](https://trac.ffmpeg.org/wiki/Encode/H.264#a1.ChooseaCRFvalue) 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](https://trac.ffmpeg.org/wiki/EncodingForStreamingSites#a-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](https://api.camio.com/#search) results.
The `timestamp` of the Reading is used to correlate the Reading with the video events that span that timestamp.
The [Search](https://api.camio.com/#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](/content/contact/index.html) 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](/content/token/index.html) 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](/content/box/index.html).
### 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](https://api.camio.com/#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
### 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](/content/getapp/index.html) 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](https://api.camio.com/#search) 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:
### 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](https://developers.google.com/chart/interactive/docs/querylanguage) 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](/content/dashboard/index.html).
## 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](https://api.camio.com/#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](https://developers.google.com/chart/interactive/docs/querylanguage), 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](https://help.camio.com/hc/en-us/articles/360022174631-What-is-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](https://developers.google.com/chart/interactive/docs/querylanguage), 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](/content/token/index.html) 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](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](https://api.camio.com/#hooks) 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_CONFIGURATION`command 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](/content/contact/index.html) 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](/content/qrcode/#data=https://camio.com/api/devices/commands/?device_id=s123/index.html) 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](https://api.camio.com/#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](/content/box/index.html) 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?](https://help.camio.com/hc/en-us/articles/115005627143-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](/content/account/index.html) 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](https://api.camio.com/#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](https://help.camio.com/hc/en-us/articles/360000491846-How-do-my-Stripe-Plans-specify-features-and-service-levels-). 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](https://api.camio.com/#hashes) 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](https://en.wikipedia.org/wiki/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](https://api.camio.com/#interest_scores) 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](/content/contact/index.html) 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](https://api.camio.com/#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](https://api.camio.com/#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](/content/domains/index.html),\
then system events from all accounts of that domain can trigger callbacks\
to endpoints of your choosing.\
\
[Contact us](/content/contact/index.html) 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](https://api.camio.com/#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](https://api.camio.com/#update-a-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](https://api.camio.com/#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](https://help.camio.com/hc/en-us/articles/115005627603-How-do-I-connect-Camio-to-my-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](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html).