.. _api_watch_lists:


Watch lists
==========================

.. _get_watch_lists:

List watch lists
-----------------------

To retrieve a list of watch lists, use the following method:

.. code::

    GET /watch-lists/

The REQUEST contains the following QUERY-STRING PARAMETERS:

+----------------------------+---------------------------+--------------------------------------------------------------------------------+
| Name                       | Type                      | Description                                                                    |                        
+============================+===========================+================================================================================+
| ``limit``                  | integer                   | Number of results to return per page.                                          |
+----------------------------+---------------------------+--------------------------------------------------------------------------------+
| ``ordering``               | string                    | Field for sorting the request results. Available fields: ``id``,               | 
|                            |                           | ``created_date``, ``modified_date``.                                           |
+----------------------------+---------------------------+--------------------------------------------------------------------------------+

The list of all available parameters can be found at ``http://<findface-ip:port>/api-docs``.

To find a specific watch list ID in the response, specify values for the ``limit`` and ``ordering`` parameters to narrow and organize the search results.

.. rubric:: CURL example

.. code::

  curl -X GET "http://<findface-ip:port>/watch-lists/?limit=2&ordering=id" \
   -H "Authorization: Token <token>"

If the response is successful (OK: 200), it returns a JSON object that contains the following parameters:

.. list-table::
     :widths: 16 10 45
     :header-rows: 1

     * - Name
       - Type
       - Description
     * - ``next_page``
       - string┃null
       - Next page.
     * - ``prev_page``
       - string┃null
       - Previous page.
     * - ``results``
       - [{...}]
       - Array containing :ref:`the following parameters <get_watch_lists_response_parameters>`. :ref:`Example <get_watch_lists_response_example>`.

.. note::

  `*` – means required parameters. 🆁 – read only.

.. _get_watch_lists_response_parameters:

.. list-table::
     :widths: 14 8 45
     :header-rows: 1

     * - Name 
       - Type 
       - Description
     * - ``id*`` 
       - integer 🆁
       - Watch list ID.
     * - ``created_date*`` 
       - date-time 🆁
       - Timestamp indicating when the watch list was created.
     * - ``modified_date*``
       - date-time 🆁
       - Timestamp indicating when the watch list was last updated.
     * - ``active`` 
       - boolean 
       - ``true`` if the watch list is active.
     * - ``name*`` 
       - string 
       - Name of the watch list.
       
         Constraints: Min 1┃Max 256 chars.
     * - ``comment``
       - string
       - Extended description.
       
         Constraints: Min 0┃Max 2048 chars.
     * - ``color`` 
       - string 
       - Color of the watch list label in hex.
        
         Constraints: Min 0┃Max 6 chars. 
     * - ``notify`` 
       - boolean 
       - ``true`` if sound notifications are enabled for the watch list.
     * - ``acknowledge`` 
       - boolean 
       - ``true`` if events that match this watch list require manual acknowledgment.
     * - ``camera_groups`` 
       - array of integers 
       - IDs of camera groups associated with the watch list.
     * - ``face_threshold`` 
       - number┃null 
       - Confidence threshold for face detection in the watch list. 
       
         Constraints: Min 0┃Max 1.
     * - ``body_threshold`` 
       - number┃null 
       - Confidence threshold for body detection in the watch list. 
       
         Constraints: Min 0┃Max 1.
     * - ``car_threshold`` 
       - number┃null
       - Confidence threshold for vehicle detection in the watch list.
       
         Constraints: Min 0┃Max 1.
     * - ``ignore_events`` 
       - boolean 
       - ``true`` if events are not created when objects from this watch list are detected.
     * - ``send_events_to_external_vms`` 
       - boolean 
       - ``true`` if events that match this watch list must be sent to an external VMS.
     * - ``origin`` 
       - string
       - Name of the application module in which the watch list was created.
        
         Constraints: Min 0┃Max 256 chars.
     * - ``collect_location`` 
       - boolean 
       - ``true`` if cards from this watch list are included in the daily search task.
        
         Used only in FindFace CIBR when the FindFace CIBR instance is configured as a puppeteer.

.. _get_watch_lists_response_example:

.. rubric:: Response example

.. code::

 {
  "next_page": null,
  "prev_page": null,
  "results": [
    {
      "id": 3,
      "created_date": "2025-05-13T12:10:28.303303Z",
      "modified_date": "2025-05-13T12:10:28.303325Z",
      "active": true,
      "name": "Parking watch list",
      "comment": "",
      "color": "cccccc",
      "notify": false,
      "acknowledge": false,
      "camera_groups": [],
      "face_threshold": null,
      "body_threshold": null,
      "car_threshold": null,
      "ignore_events": false,
      "send_events_to_external_vms": false,
      "origin": "ffsecurity",
      "collect_location": false
    },
    {
      "id": 2,
      "created_date": "2025-05-13T11:37:43.593898Z",
      "modified_date": "2025-07-01T15:42:33.537511Z",
      "active": true,
      "name": "Shopping mall watch list",
      "comment": "",
      "color": "cccccc",
      "notify": false,
      "acknowledge": true,
      "camera_groups": [
        2,
        3
      ],
      "face_threshold": 0.702,
      "body_threshold": 0.65,
      "car_threshold": 0.65,
      "ignore_events": true,
      "send_events_to_external_vms": false,
      "origin": "ffsecurity",
      "collect_location": false
    }
  ]
 }
 
.. _add_a_new_watch_list:

Create a new watch list
-----------------------

To add a new watch list, use the following method:

.. code::
    
    POST /watch-lists/

The REQUEST BODY is required and contains an application/json object with the following parameters:

.. list-table::
     :widths: 14 8 45
     :header-rows: 1

     * - Name 
       - Type 
       - Description
     * - ``active``
       - boolean 
       - If ``true``, the watch list will be active.
     * - ``name*`` 
       - string 
       - Name of the watch list.
       
         Constraints: Min 1┃Max 256 chars.
     * - ``comment``
       - string
       - Extended description.
       
         Constraints: Min 0┃Max 2048 chars.
     * - ``color``
       - string 
       - Color of the watch list label in hex. 
        
         Constraints: Min 0┃Max 6 chars. 
     * - ``notify``
       - boolean 
       - If ``true``, sound notifications will be enabled for the watch list.
     * - ``acknowledge``
       - boolean  
       - If ``true``, events that match this watch list will require manual acknowledgment. 
     * - ``camera_groups`` 
       - array of integers 
       - IDs of camera groups associated with the watch list.
     * - ``face_threshold``
       - number┃null 
       - Confidence threshold for face detection in the watch list. 
       
         Constraints: Min 0┃Max 1.
     * - ``body_threshold``
       - number┃null  
       - Confidence threshold for body detection in the watch list. 
       
         Constraints: Min 0┃Max 1.
     * - ``car_threshold``
       - number┃null 
       - Confidence threshold for vehicle detection in the watch list.
       
         Constraints: Min 0┃Max 1.
     * - ``ignore_events``
       - boolean 
       - If ``true``, events will not be created when objects from this watch list are detected.
     * - ``send_events_to_external_vms``
       - boolean
       - If ``true``, events that match this watch list will be sent to an external VMS.
     * - ``origin``
       - string
       - Name of the application module in which the watch list will be created.
        
         Constraints: Min 0┃Max 256 chars.
     * - ``collect_location`` 
       - boolean 
       - If ``true``, cards from this watch list can be included in the daily search task.
        
         Used only in FindFace CIBR when the FindFace CIBR instance is configured as a puppeteer.

.. rubric:: Request example

.. tip::

  This example is provided for reference only. Substitute your own values in the corresponding fields. You only need to fill in the required fields; all other fields will use their default values.

.. code::

 {
  "active": false,
  "name": "A",
  "comment": "AAAAAA",
  "color": "A",
  "notify": false,
  "acknowledge": false,
  "camera_groups": [
    0
  ],
  "face_threshold": 0,
  "body_threshold": 0,
  "car_threshold": 0,
  "ignore_events": false,
  "send_events_to_external_vms": false,
  "origin": "A"
 }

For example, you can send these parameters:

.. code::

 {
  "active": true,
  "name": "new watch list",
  "comment": "sample",
  "color": "35a2ee"
 }

.. rubric:: CURL example 

.. code::

  curl -X POST "http://<findface-ip:port>/watch-lists/" \
   -H "Authorization: Token <token>" \
   -H "Content-Type: application/json" \
   -d '{"active":true,"name":"new watch list","comment":"sample","color":"35a2ee"}'

If the response is successful (Created: 201), it returns a JSON object that contains :ref:`parameters <get_watch_lists_response_parameters>`. :ref:`Example <add_watch_list_response_example>`.

.. _add_watch_list_response_example:

.. rubric:: Response example

.. code::

 {
  "id": 9,
  "created_date": "2025-07-22T09:36:00.253232Z",
  "modified_date": "2025-07-22T09:36:00.253273Z",
  "active": true,
  "name": "new watch list",
  "comment": "sample",
  "color": "35a2ee",
  "notify": false,
  "acknowledge": false,
  "camera_groups": [],
  "face_threshold": null,
  "body_threshold": null,
  "car_threshold": null,
  "ignore_events": false,
  "send_events_to_external_vms": false,
  "origin": "ffsecurity",
  "collect_location": false
 }

Use the watch list ID in the ``POST`` request to :ref:`create a new record <create_new_record>`.

Useful requests
--------------------------

.. code::
  
  GET /watch-lists/
  POST /watch-lists/
  GET /watch-lists/{id}/
  DELETE /watch-lists/{id}/
  PATCH /watch-lists/{id}/
  POST /watch-lists/{id}/purge/
  GET /watch-lists/count/
  POST /watch-lists/purge_all/