Flussonic Watcher API v2 (22.01.1-340)

Download OpenAPI specification:Download

This is a comprehensive Flussonic Watcher API v2 guide. The document is under development and may not include all currently available endpoints. While we are working on it, you may refer to the documentation or on our GitHub page to find missing commands.

The API includes options to create, update, or delete all essential entities in Watcher including cameras, organizations, users, etc. You can use it to integrate Watcher with your existing billing, access control or other system, or implement your own web UI for Watcher server, or for any other legal purpose.

Authentication

basicAuth

You can use three types of tokens called API keys in Watcher terms. Please refer to this article for details on how to get and use them.

Security Scheme Type HTTP
HTTP Authorization Scheme basic

analytics

List of face detection events

Returns the list of all face detection events from Watcher database.

Authorizations:

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get face preview

Returns the thumbnail of the face detection event.

Use /vsaas/api/v2/analytics/faces to get the list of all face detection events and find out the ID of the desired event.

Authorizations:

Responses

List of LPR events

Returns the list of all License Plate Recognition events from Watcher database.

Authorizations:
query Parameters
offset
integer

Paging offset, i.e. the number of the first sequential item to be first in the list.

limit
integer

Paging limit, i.e. the number of items on the page starting from the first one defined by offset.

event_type
any (license_plate_event_type)

Event type:

  • license_plate for standard license plate recognition.
  • emergency for an emergency vehicle detected (fire truck, police car, or ambulance). LP may not be detected.
  • no_license_plate for a vehicle without license plate detected.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get LPR event preview

Returns the thumbnail of the License Plate Recognition event.

Use /vsaas/api/v2/analytics/license_plates to get the list of all LPR events and find out the ID of the desired event.

Authorizations:

Responses

List of Persons

This method will return the list of persons that are available depending on the API key in use.

With user-specific keys, the user must have Watcher Administrator or Organization Owner (Administrator) permissions in order to get response, otherwise the "Forbidden" error code will be returned.

Only the persons available to the user are returned:

  • All persons for Watcher Administrator
  • Persons belonging to the owned Organization(s) for Organization Owner

You can also set some search conditions in the query after the question mark. Available parameters are shown below.

For example, to get the list of persons in specific list, if it is available with session permissions, specify the list ID after the question mark like this: /vsaas/api/v2/analytics/persons?person_list=4.

Authorizations:
query Parameters
offset
integer

Paging offset, i.e. the number of the first sequential item to be first in the list.

limit
integer

Paging limit, i.e. the number of items on the page starting from the first one defined by offset.

search
string

The condition to search for persons by name.

utc_from
integer <utc_seconds>

The beginning of the time interval to search for persons within by the last seen time.

utc_to
integer <utc_seconds>

The end of the time interval to search for persons within by the last seen time.

person_list
string

ID of the person list to get the persons from.

external_id
string

The person ID in an external database. Please refer to response for details on this parameter.

organization_id
integer

Organization filter to get the list of persons assigned with the specified Organization.

sort
string
Example: sort=-last_seen_at,name

Composite sort direction. Specify field name(s) using comma , as a separator.

Default sorting order is alphabetical or ascending. Place - before the field name to sort in reverse alphabetical order or descending.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a Person

Calling this method will create a new person entity in Watcher.

With user-specific API keys, the user must have Watcher Administrator permissions in order to create a person in any Organization or Organization Owner permissions in order to create a person in the owned Organization.

The required parameter is person's name. Some of the person's parameters (as seen in "Get one Person" request) including ID and dates will be assigned automatically and returned in response among other parameters.

It is strongly recommended to include the following in the request body:

  • organization_id of the owned Organization for the Organization Owner session or any Organization for Watcher Administrator session;
  • data in multipart/form-data format of the request body schema.

The request may be denied without those parameters.

Authorizations:
Request Body schema:
name
required
string

The human-readable name of the person for displaying in the UI.

person_list_id
integer or null <integer> (person_list_id)

Identifier of the person list to add the person into.

note
string (note)

An arbitrary text comment that is displayed in the person profile.

external_id
string or null (external_id)

The person's ID in a third party system, for example Access Control System, CRM, etc. This ID allows mapping Watcher person database with an external database for the integration purposes.

organization_id
integer or null <integer> (organization_id)

Identifier of the Organization which the person belongs to.

Responses

Request samples

Content type
{
  • "name": "string",
  • "person_list_id": 1,
  • "note": "string",
  • "external_id": "string",
  • "organization_id": 1
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "person_list_id": 0,
  • "note": "string",
  • "external_id": "string",
  • "organization_id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "first_seen_at": "2019-08-24T14:15:22Z",
  • "last_seen_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "<User 1:admin>",
  • "organization": {
    },
  • "person_list": {
    }
}

Delete a Person

This method allows you to delete a person having the specified ID.

The result may differ depending on the API key in use.

With user-specific keys, the user must have Watcher Administrator permissions in order to delete a person from any list or Organization Owner permissions in order to delete a person from a list that belongs to the owned Organization.

Authorizations:

Responses

Get one Person

Returns parameters of a single person having the specified ID.

With user-specific API key, the user must have Watcher Administrator permissions in order to get a person from any list or Organization Owner permissions in order to get a person from a list that belongs to the owned Organization.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "person_list_id": 0,
  • "note": "string",
  • "external_id": "string",
  • "organization_id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "first_seen_at": "2019-08-24T14:15:22Z",
  • "last_seen_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "<User 1:admin>",
  • "organization": {
    },
  • "person_list": {
    }
}

Update Person data

Updates one or several parameters of a single person having the specified ID.

With user-specific API key, the user must have Watcher Administrator permissions in order to update a person from any list or Organization Owner permissions in order to update a person from a list that belongs to the owned Organization.

You may include only changed parameters in the request body.

Authorizations:
Request Body schema:
name
string (name)

The human-readable name of the person for displaying in the UI.

person_list_id
integer or null <integer> (person_list_id)

Identifier of the person list to add the person into.

note
string (note)

An arbitrary text comment that is displayed in the person profile.

external_id
string or null (external_id)

The person's ID in a third party system, for example Access Control System, CRM, etc. This ID allows mapping Watcher person database with an external database for the integration purposes.

organization_id
integer or null <integer> (organization_id)

Identifier of the Organization which the person belongs to.

Responses

Request samples

Content type
{
  • "name": "string",
  • "person_list_id": 1,
  • "note": "string",
  • "external_id": "string",
  • "organization_id": 1
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "person_list_id": 0,
  • "note": "string",
  • "external_id": "string",
  • "organization_id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "first_seen_at": "2019-08-24T14:15:22Z",
  • "last_seen_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "<User 1:admin>",
  • "organization": {
    },
  • "person_list": {
    }
}

Get Person's photo

Returns the person's reference photo (i.e. preview image) in a binary format.

With user-specific API key, the user must have Watcher Administrator permissions in order to get the photo of a person from any list or Organization Owner permissions in order to get the photo of a person from a list that belongs to the owned Organization.

Authorizations:

Responses

auth

Log a user in

The method will return all parameters of the created session for the logged-in user including the session parameter that can be used in all other requests as x-vsaas-session API key

Authorizations:
Request Body schema: application/json
login
required
string

User's login

password
required
string

User's password

Responses

Request samples

Content type
application/json
{
  • "login": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "can_edit_organizations": { },
  • "can_edit_settings": { },
  • "can_view_organizations": { },
  • "domain_id": { },
  • "id": 0,
  • "is_admin": false,
  • "is_domain_admin": { },
  • "is_logged_in": { },
  • "is_organization_admin": { },
  • "locale": "",
  • "locales": { },
  • "login": "Guest",
  • "notification_email": "",
  • "organizations": { },
  • "readonly": false,
  • "server_info": { },
  • "session": true,
  • "unread_messages_count": { }
}

cameras

List of cameras

Returns camera list. Please note that this API call has 2 flavors: admin mode and user mode. The mode is defined by an API key.

The method will return different data for different modes:

  • Admin mode with X-Vsaas-Api-Key: you get all cameras with all configuration information.
  • User mode with X-Vsaas-User or X-Vsaas-Session: the response contains only cameras visible to the specified user with reduced set of fields.

You can switch between "camera" and "camera_response_limited" tabs in the Responses section below to see which parameters are returned in each mode.

Authorizations:
query Parameters
offset
integer

Paging offset, i.e. the number of the first sequential item to be first in the list.

limit
integer

Paging limit, i.e. the number of items on the page starting from the first one defined by offset.

Responses

Response samples

Content type
application/json
[
  • {
    }
]