Folder management API¶

You can use folder management API requests to integrate Watcher with billing or to develop your own application/web interface for Watcher, etc. Depending on the requirements for the integration/application, you may want to create, delete or change folders, change their hierarchy, find out which users have access to the folder and which cameras are added to it, which folders the user has access to. The Watcher API supports all of these requests.

See Adding Cameras to Folders or Favorites for details on folders. Please refer to Integration with existing billing system for details on cameras provisioning and billing integration.

This section provides examples of API requests for managing folders. Click here to see the full list of response and request parameters.

You should use one of the keys for the API request authorization. The examples in this section are given with the x-vsaas-session key: this means that the user on whose behalf the requests are made must have the rights to perform the corresponding actions. Please refer to API request authorization ways for details on the key types.

Getting a list of folders¶

To get a list of folders in a specific Organization, use the following query

GET YOUR_WATCHER_URL/vsaas/api/v2/organizations/(organization ID)/folders

If you include the current user's x-vsaas-session key in the header, the request will return a list of folders available to the current user. To get a list of all folders in an organization, use x-vsaas-api-key.

Any organization has a default root folder with the same name as Organization.

Example of requesting folders in an organization with ID 6

curl 'http://localhost/vsaas/api/v2/organizations/6/folders' \
-H 'x-vsaas-session: tPbYSDBiaX4C8_BMuySsr63r-qQ'

Two folders in the Organization: the default root folder "Cameras" and its subfolder "New folder" created by some user.

[
    {
        "map_topleft": null,
        "parent_id": null,
        "map_topright": null,
        "order_num": 1,
        "coordinates": null,
        "camera_count": 2,
        "map_bottomleft": null,
        "organization_id": 6,
        "id": 7,
        "title": "Cameras",
        "level": 0
    },
    {
        "map_topleft": null,
        "parent_id": 7,
        "map_topright": null,
        "order_num": 1,
        "coordinates": null,
        "camera_count": 1,
        "map_bottomleft": null,
        "organization_id": 6,
        "id": 18,
        "title": "New folder",
        "level": 1
    }
]

Creating a folder¶

Use the following request to create a folder

POST YOUR_WATCHER_URL/vsaas/api/v2/organizations/(organization ID)/folders

Required parameters:

• title (string) — folder name
• parent_id (integer) — parent folder ID.

Optional parameters:

• order_num (integer) — the sequential number of the folder in the list. If the parameter is not specified or is already in use, the next free sequence number is assigned.

If you want to create floor plans, use the following parameters:

• coordinates (string) — the image center coordinates, latitude and longitude are separated by a space, the decimal separator is a dot.
• map_bottomleft (string) — coordinates of the lower left corner of the image.
• map_topleft (string) — coordinates of the upper left corner of the image.
• map_topright (string) — coordinates of the upper right corner of the image.

• map_file (object) — floor plan image:

  • b64_content (string) — base64 encoded image
  • delete (boolean) — true to delete previously used image (if any), or false to keep it
  • mime_type (string) — MIME type of the image

Example

curl --request POST \
--url http://localhost/vsaas/api/v2/organizations/6/folders \
--header 'content-type: application/json' \
--header 'x-vsaas-session: <vsaas_session>' \
--data '{
"title": "Folder name",
"parent_id": 7
}'

The request will return the parameters of the created folder. Note that the map_file object in the response contains only the url parameter.

{"map_topleft":null,
"parent_id":7,
"map_topright":null,
"map_file":{"url":null},
"order_num":4,
"coordinates":null,
"camera_count":0,
"map_bottomleft":null,
"organization_id":6,
"id":22,
"title":"Folder name",
"level":1}

Changing the folder¶

Use the following request to change one or several parameters of the folder

PUT YOUR_WATCHER_URL/vsaas/api/v2/organizations/(organization ID)/folders/(folder ID)

You can pass the same parameters as when creating a folder, as well as the following additional parameters that allow you to change the position of the folder in the tree:

move_after (integer) — the identifier of the folder to be followed by the current folder. move_before (integer) — the identifier of the folder before which the current folder is to be placed. move_inside (integer) — the identifier of the folder where the current folder should be placed.

You will find detailed examples of using these parameters below.

Example changing folder name

curl --request PUT \
--url http://localhost/vsaas/api/v2/organizations/1/folders/1/ \
--header 'content-type: application/json' \
--header 'x-vsaas-session: <vsaas_session>' \
--data '{
"title": "toor"
}'

The request will return all the parameters of the changed object similar to the example above.

Changing the folder position in the tree:¶

The examples below are for the following folder tree in an Organization:

Moving a folder¶

curl --request PUT \
--url http://localhost/vsaas/api/v2/organizations/1/folders/3/ \
--header 'content-type: application/json' \
--header 'x-vsaas-session: <vsaas_session>' \
--data '{
"move_after": 4
}'

Result:

Changing a folder's parent¶

curl --request PUT \
--url http://localhost/vsaas/api/v2/organizations/1/folders/3/ \
--header 'content-type: application/json' \
--header 'x-vsaas-session: <vsaas_session>' \
--data '{
"move_inside": 4
}'

Result:

Removing the folder¶

The request to remove the folder is:

DELETE YOUR_WATCHER_URL/vsaas/api/v2/organizations/(organization ID)/folders/(folder ID)

Example

curl --request DELETE \
--url 'http://localhost/vsaas/api/v2/organizations/1/folders/1' \
--header 'x-vsaas-session: <vsaas_session>' 

In case of successful deletion, Watcher will respond with {"success":true}

Request for cameras in the folder¶

Use the following request to find out which cameras are added to the folder:

GET YOUR_WATCHER_URL/vsaas/api/v2/cameras?folder_id=(folder ID)

Example

curl --request GET \
--url 'http://localhost/vsaas/api/v2/cameras?folder_id=7' \
--header 'x-vsaas-session: <vsaas_session>'

The response will contain all parameters of all cameras added to the folder. Cameras from child folders are not included in the response.

In this case, the response contains two cameras:

[
    {
        "agent_key": null,
        "agent_id": null,
        "thumbnails_url": "",
        "motion_detector_enabled": false,
        "static": true,
        "onvif_profile": null,
        "groups": [],
        "precise_thumbnails": false,
        "enabled": true,
        "dvr_space": null,
        "folder_id": 7,
        "precise_thumbnails_days": 0,
        "dvr_lock_days": 1,
        "agent_model": null,
        "user_attributes": {},
        "playback_config": {
            "token": "2.-s9tHGUHAAEABcXhj_yu3vqQhCc5l9Zv1aS-onP8IcVoG4Pl"
        },
        "thumbnails": false,
        "folder_coordinates": null,
        "substream_url": "",
        "preset": {
            "vision_alg": null,
            "vision_params": {},
            "vision_areas": null,
            "is_adjustable": true,
            "vision_enabled": null,
            "dvr_depth": 2,
            "domain_id": 1,
            "dvr_space": null,
            "vision_gpu": null,
            "id": 8,
            "is_default": true,
            "dvr_lock_days": 1,
            "title": "2+1days_adjustable",
            "is_deleted": false
        },
        "comment": "",
        "vision_alg": null,
        "last_change": {
            "object_type": "Camera",
            "created_at": 1623922927,
            "object_id": "samplecamera2-1584a116d9",
            "user": "admin"
        },
        "streamer_id": 1,
        "onvif_ptz": false,
        "preset_id": 8,
        "dvr_path": "/dvr",
        "coordinates": "",
        "permissions": {
            "dvr": true,
            "ptz": true,
            "edit": true,
            "view": true,
            "actions": true
        },
        "postal_address": "",
        "agent_serial": null,
        "dvr_depth": 2,
        "organization_id": 6,
        "video_only": false,
        "external_id": null,
        "stream_url": "file://vod/sample-10s.mp4 ",
        "agent_status": null,
        "vision_areas": null,
        "onvif_url": null,
        "vision_enabled": null,
        "last_event_time": null,
        "stream_status": {
            "alive": false,
            "lifetime": 5948,
            "source_error": null,
            "http_port": 80,
            "https_port": null,
            "bitrate": 4294,
            "server": "localhost"
        },
        "name": "samplecamera2-1584a116d9",
        "has_actions": false,
        "vision_gpu": null,
        "title": "SampleCamera2"
    },
    {
        "agent_key": null,
        "agent_id": null,
        "thumbnails_url": "",
        "motion_detector_enabled": false,
        "static": true,
        "onvif_profile": null,
        "groups": [],
        "precise_thumbnails": false,
        "enabled": true,
        "dvr_space": null,
        "folder_id": 7,
        "precise_thumbnails_days": 0,
        "dvr_lock_days": 1,
        "agent_model": null,
        "user_attributes": {},
        "playback_config": {
            "token": "2.-s9tHGUHAAEABcXhj_yu3gCkwPvOTwRbY3O60MZ0Qb117UHv"
        },
        "thumbnails": false,
        "folder_coordinates": null,
        "substream_url": "",
        "preset": {
            "vision_alg": null,
            "vision_params": {},
            "vision_areas": null,
            "is_adjustable": false,
            "vision_enabled": null,
            "dvr_depth": 1,
            "domain_id": 1,
            "dvr_space": null,
            "vision_gpu": null,
            "id": 7,
            "is_default": true,
            "dvr_lock_days": 1,
            "title": "1+1days_non-adjustable",
            "is_deleted": false
        },
        "comment": "",
        "vision_alg": null,
        "last_change": {
            "object_type": "Camera",
            "created_at": 1623923311,
            "object_id": "samplecamera4-fd2f695a2e",
            "user": "admin"
        },
        "streamer_id": 1,
        "onvif_ptz": false,
        "preset_id": 7,
        "dvr_path": "/dvr",
        "coordinates": "",
        "permissions": {
            "dvr": true,
            "ptz": true,
            "edit": true,
            "view": true,
            "actions": true
        },
        "postal_address": "",
        "agent_serial": null,
        "dvr_depth": 1,
        "organization_id": 6,
        "video_only": false,
        "external_id": null,
        "stream_url": "file://vod/sample-5s.mp4 ",
        "agent_status": null,
        "vision_areas": null,
        "onvif_url": null,
        "vision_enabled": null,
        "last_event_time": null,
        "stream_status": {
            "alive": false,
            "lifetime": 6008,
            "source_error": null,
            "http_port": 80,
            "https_port": null,
            "bitrate": 4081,
            "server": "localhost"
        },
        "name": "samplecamera4-fd2f695a2e",
        "has_actions": false,
        "vision_gpu": null,
        "title": "SampleCamera4"
    }
]

Users in the folder¶

Getting a list of users in the folder¶

Use the following query to get a list of users who have permission to access the folder

GET YOUR_WATCHER_URL/vsaas/api/v2/organizations/(organization ID)/folders/(folder ID)/users

curl --request GET \
--url http://localhost/vsaas/api/v2/organizations/1/folders/1/users \
--header 'x-vsaas-session: <vsaas_session>' 

[
    {
        "can_use_ptz": true,
        "can_use_actions": true,
        "can_view_dvr": true,
        "user_id": 16,
        "dvr_depth_limit": null
    },
    {
        "can_use_ptz": false,
        "can_use_actions": false,
        "can_view_dvr": true,
        "user_id": 14,
        "dvr_depth_limit": 1
    }
]

Viewing specific user's permissions in all available folders¶

To get a list of user permissions in all folders available to them, use the query

GET YOUR_WATCHER_URL/vsaas/api/v2/users/(user_id)?fields=folders_permissions'

curl --request GET \
--url http://localhost/vsaas/api/v2/users/2?fields=folders_permissions' \
--header 'x-vsaas-session: <vsaas_session>' 

{
    "folders_permissions": [
        {
            "folder_id": 1,
            "organization_id": 1,
            "can_view_dvr": true,
            "dvr_depth_limit": 365,
            "can_use_ptz": false,
            "can_use_actions": false
        },
        {
            "folder_id": 25,
            "organization_id": 12,
            "can_view_dvr": false,
            "dvr_depth_limit": null,
            "can_use_ptz": false,
            "can_use_actions": false
        }
    ]
}

Viewing specific user's permissions in the folders of specific Organization¶

To find out what permissions a user has to the folders of the Organization, use the following query:

GET YOUR_WATCHER_URL/vsaas/api/v2/users/(user_id)?fields=folders_permissions'

curl --request GET \
--url http://localhost/vsaas/api/v2/organizations/1/users/2?fields=folders_permissions' \
--header 'x-vsaas-session: <vsaas_session>' 

{
    "folders_permissions": [
        {
            "folder_id": 1,
            "can_view_dvr": true,
            "dvr_depth_limit": 6,
            "can_use_ptz": false,
            "can_use_actions": false
        },
        {
            "folder_id": 13,
            "can_view_dvr": false,
            "dvr_depth_limit": null,
            "can_use_ptz": false,
            "can_use_actions": false
        }
    ]
}

Adding the user to the folder¶

Use the following request to give the user permissions to view live video or archive or control PTZ

POST YOUR_WATCHER_URL/vsaas/api/v2/organizations/(organization ID)/folders/(folder ID)/users

Request parameters:

• user_id (integer) — user's ID
• can_use_ptz (bool) — true to allow PTZ control, or false to forbid
• can_view_dvr (bool) — true to allow access to DVR, or false to forbid
• can_use_actions (bool) — true to allow actions management, or false to forbid
• dvr_depth_limit (integer) — the number of archive days available to the user; null stands for unlimited access

curl --request POST \
--url http://localhost/vsaas/api/v2/organizations/1/folders/1/users \
--header 'content-type: application/json' \
--header 'x-vsaas-session: <vsaas_session>' \
--data '{
"can_view_dvr": 10,
"can_use_ptz": 1,
"user_id": 14
}'

{
    "can_use_actions": null,
    "dvr_depth_limit": null,
    "can_use_ptz": 1,
    "user_id": 14,
    "can_view_dvr": 10
}

Changing user permissions in the folder¶

Use the following request to change the user's permissions to view live video and archive and control PTZ

POST YOUR_WATCHER_URL/vsaas/api/v2/organizations/(organization ID)/folders/(folder ID)/users

The request parameters are the same as when assigning permissions (see above).

curl --request PUT \
--url http://localhost/vsaas/api/v2/organizations/1/folders/1/users/1/ \
--header 'content-type: application/json' \
--header 'x-vsaas-session: <vsaas_session>' \
--data '{
"can_use_ptz": 1,
"can_view_dvr": 5
}'

The request will return the user's permissions to the folder similar ro the example above.

Deleting the user from the folder¶

Use the following request to disable user access to the folder

DELETE https://YOUR_WATCHER_URL/vsaas/api/v2/organizations/(organization_id)/folders/(folder_id)/users/(user_id)

curl --request DELETE \
--url http://localhost/vsaas/api/v2/organizations/1/folders/1/users/1/ \
--header 'x-vsaas-session: <vsaas_session>' \

If the request is successful, Watcher will return {"success":true}.