Organization management API¶

You can use Organization management API requests to integrate Watcher with billing or to develop your own application/web interface for Watcher, etc. For example, if Provider creates Organizations, presets and users from the Watcher interface and assigns the subscriber as the owner of the Organization, then the billing will most likely need to request information about Organization settings that the subscriber has chosen. If billing is a control system, implement the requests for creating, changing and deleting Organizations, limiting DVR, the number of cameras and users in the Organization.

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 organizations. 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 Organizations¶

For example: if you created organizations from the Watcher interface and want to get a list of organizations and their parameters in billing, use the following query

GET YOUR_WATCHER_URL/vsaas/api/v2/organizations/

Example:

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

This response contains information on three Organizations: Default, HOME, Cafe

[
    {
        "mosaic_count": 4,
        "id": 6,
        "domain": {
            "id": 1,
            "title": "Flussonic Watcher"
        },
        "user_count": 2,
        "user_limit": 2000,
        "dvr_limit": 1000,
        "can_view_stats": true,
        "camera_count": 3,
        "can_edit_users": true,
        "camera_limit": 5000,
        "owner": {
            "id": 14,
            "login": "Subscriber 1"
        },
        "can_edit_cameras": true,
        "is_member": true,
        "is_default": false,
        "title": "Cafe"
    },
    {
        "mosaic_count": 0,
        "id": 1,
        "domain": {
            "id": 1,
            "title": "Flussonic Watcher"
        },
        "user_count": 2,
        "user_limit": 1000,
        "dvr_limit": 100,
        "can_view_stats": true,
        "camera_count": 1,
        "can_edit_users": true,
        "camera_limit": 1000,
        "owner": {
            "id": 1,
            "login": "admin"
        },
        "can_edit_cameras": true,
        "is_member": true,
        "is_default": true,
        "title": "Default"
    },
    {
        "mosaic_count": 0,
        "id": 3,
        "domain": {
            "id": 1,
            "title": "Flussonic Watcher"
        },
        "user_count": 3,
        "user_limit": 2000,
        "dvr_limit": 1000,
        "can_view_stats": false,
        "camera_count": 1,
        "can_edit_users": true,
        "camera_limit": 5000,
        "owner": {
            "id": 3,
            "login": "Subscriber 2"
        },
        "can_edit_cameras": true,
        "is_member": true,
        "is_default": false,
        "title": "HOME"
    }
]

Creating an Organization¶

Use the following request to create an Organization

POST YOUR_WATCHER_URL/vsaas/api/v2/organizations/

Request parameters:

title (string) — required parameter, name of the created organization.
camera_limit (integer) — limitation on the number of cameras. If the parameter is not specified or is equal to 0, then the default limit of 1000 is set.
dvr_limit (integer) — limitation on the disk space. If the parameter is not specified, then the default limit of 100 GB will be set.
owner_id (integer) — the identifier of the user who is the administrator (owner) of the Organization. If this parameter is not specified, then the organization will be created without an owner, and no one, even the Super Administrator, will have rights to edit the settings of cameras, users and mosaics in this organization. A user with Watcher Administrator or Super Administrator rights will be able to change the owner of the Organization. Please refer to Managing users and their permissions for details on the permissions mechanism.
user_limit (integer) — limitation of the number of users. If the parameter is not specified, then the default value of 1000 will be set.

Example:

curl --request POST \
--url http://127.0.0.1/vsaas/api/v2/organizations \
--header 'content-type: application/json' \
--header 'x-vsaas-session: <vsaas_session>' \
--data '{
"title": "Org2"
}'

{
    "id": 12,
    "domain": {
        "id": 1,
        "title": "Flussonic Watcher"
    },
    "user_limit": 1000,
    "dvr_limit": 100,
    "camera_limit": 1000,
    "owner": null,
    "title": "Org2"
}

Information about the Organization¶

Use the following request to get information about specific Organization

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

Example with ID 1

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

{
    "mosaic_count": 0,
    "id": 1,
    "domain": {
        "id": 1,
        "title": "Flussonic Watcher"
    },
    "user_count": 2,
    "user_limit": 1000,
    "dvr_limit": 100,
    "can_view_stats": true,
    "camera_count": 1,
    "can_edit_users": true,
    "camera_limit": 1000,
    "owner": {
        "id": 1,
        "login": "admin"
    },
    "can_edit_cameras": true,
    "is_member": true,
    "is_default": true,
    "title": "Default"
}

Changing the Organization¶

Use the following request to change one or several parameters of the Organization:

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

The request parameters are the same as in the request to create the Organization. You can include only the parameters you want to change in the request body.

Example: change the Organization with ID = 12

curl --request PUT \
--url http://127.0.0.1/vsaas/api/v2/organizations/12 \
--header 'content-type: application/json' \
--header 'x-vsaas-session: <vsaas_session>' \
--data '{
"title": "test org 2"
}'

Watcher will return an updated list of Organization parameters, similar to the example above.

Deleting the Organization¶

Use the following request to delete the Organization

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

Please note that the 'force' header must be added to the request, otherwise the request will return an error. This is because any Organization has a default folder that cannot be deleted while the Organization cannot be deleted normally as long as it has dependent objects (i.e. folders).

Example:

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

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