.. _api_object:


Objects
=============================

Add a face object
---------------------------

To add a new face object to a record of individuals, use the following method:

.. code::

    POST /objects/faces/

The added object contains a source photo, thumbnail, and other attributes.

.. tip::
    
   - To add a new body object to a record of individuals, use ``/objects/bodies/`` instead of ``/objects/faces/``.
   - To add a new vehicle object to a vehicle record, use ``/objects/cars/`` instead of ``/objects/faces/``.

The REQUEST BODY is required and contains multipart/form-data with the following parameters: 

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

     * - Name 
       - Type 
       - Description
     * - ``create_from`` 
       - string
       - Can contain one of the following reference expressions that identify a source object from which a new object will be created: 

         - ``detection:<detection_id>``: use the ``id`` of an object detected in a source image with ``POST /detect``. In the ``source_photo`` parameter, specify the same source image that was used with ``POST /detect``. 
         - ``{face|body|car}event:<event_id>``: use an event containing an object of a specific type (``face``, ``body``, or ``car``) to create a new object corresponding to the one from the event. The ``source_photo`` parameter must be empty when using this expression.
         - ``{face|body|car}object:<object_id>``: use an existing object of a specific type (``face``, ``body``, or ``car``) as a template to create a new object. The ``source_photo`` parameter must be empty when using this expression.
          
         Valid expressions for each method: 

         - ``POST /objects/faces/``: ``faceevent:<event_id>``, ``faceobject:<object_id>``, ``detection:<detection_id>``.
         - ``POST /objects/bodies/``: ``bodyevent:<event_id>``, ``bodyobject:<object_id>``, ``detection:<detection_id>``.
         - ``POST /objects/cars/``: ``carevent:<event_id>``, ``carobject:<object_id>``, ``detection:<detection_id>``.
     * - ``detect_id`` 
       - string
       - Auxiliary parameter.
     * - ``mf_selector`` 
       - enum
       - Defines the default behavior to apply when multiple objects are detected in the source image provided via the ``source_photo`` parameter, and the ``create_from`` parameter does not include the ``detection:<detection_id>`` expression. 

         Default: ``reject``. 
 
         Allowed values: 
       
         - ``reject``: reject the request if the source image contains multiple objects. 
         - ``biggest``: select the largest object in the source image.
     * - ``upload_list`` 
       - integer
       - ID of a list of records grouped into a single batch upload. 
        
         Service parameter used only by the frontend.
     * - ``source_photo`` 
       - binary
       - Source image. 

         Required parameter if the ``create_from`` parameter includes the ``detection:<detection_id>`` expression. Otherwise, the parameter is optional.
     * - ``frame_coords_left`` 
       - integer
       - X-coordinate (in pixels) of the top-left corner of the object’s bounding box.
     * - ``frame_coords_top`` 
       - integer
       - Y-coordinate (in pixels) of the top-left corner of the object’s bounding box.
     * - ``frame_coords_right`` 
       - integer
       - X-coordinate (in pixels) of the bottom-right corner of the object’s bounding box.
     * - ``frame_coords_bottom`` 
       - integer
       - Y-coordinate (in pixels) of the bottom-right corner of the object’s bounding box. 
     * - ``active`` 
       - boolean
       -  If ``true``, the added object will be active. 
         
          Default: ``true``.
     * - ``card`` 
       - integer
       - ID of the record that will store the added object. 
        
         Required parameter.
     
.. rubric:: CURL example

.. code::

 curl -X POST "http://<findface-ip:port>/objects/faces/" \
   -H "Authorization: Token <token>" \
   -H "Content-Type: multipart/form-data" \
   -F "create_from=detection:d1svumckd5qs72mq52b0" \
   -F "source_photo=@sample_face.jpg" \
   -F "card=1"

.. tip::

  Replace ``sample_face.jpg`` with the full path if the file is not in your current working directory.
  Example: ``"source_photo=@/home/ubuntu/sample_face.jpg"``

For example, to add a new face object, follow these steps:

#. Use the ``POST /detect`` method to :ref:`detect a face in a photo <api_detect>` and copy the ``id`` of the detected face.
#. | Send the ``POST /objects/faces/`` request with the following parameters:

       - ``create_from``: specify the ``id`` from step 1 in the following format: ``detection:<detection_id>``.
       - ``source_photo``: provide the same image that was used in the ``POST /detect`` request.
       - ``card``: specify the ID of the record to which the new face object will be added.
      
   | If the response is successful (Created: 201), it returns a JSON object that contains the following :ref:`parameters <add_objects_response_parameters>`. :ref:`Example <add_objects_response_example>`.

.. note::

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

.. _add_objects_response_parameters:

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

     * - Name 
       - Type 
       - Description
     * - ``card*``
       - integer
       - Record ID.
     * - ``created_date*``
       - date-time 🆁
       - Timestamp indicating when the object was created.
     * - ``modified_date*``
       - date-time 🆁
       - Timestamp indicating when the object was last updated.
     * - ``source_photo_name*``
       - string 🆁
       - Filename of the source image used to create the object.
     * - ``source_photo``
       - uri
       - URL of the source image file, whose name is specified in the ``source_photo_name`` parameter.  
     * - ``thumbnail*`` 
       - uri 🆁
       - URL of the object's thumbnail image.
     * - ``frame_coords_left``
       - integer
       - X-coordinate (in pixels) of the top-left corner of the object’s bounding box.
     * - ``frame_coords_top`` 
       - integer
       - Y-coordinate (in pixels) of the top-left corner of the object’s bounding box.
     * - ``frame_coords_right`` 
       - integer
       - X-coordinate (in pixels) of the bottom-right corner of the object’s bounding box.
     * - ``frame_coords_bottom`` 
       - integer
       - Y-coordinate (in pixels) of the bottom-right corner of the object’s bounding box.
     * - ``active`` 
       - boolean
       - ``true`` if the object is active.
        
         Default: ``true``.
     * - ``features*`` 
       - object
       - Contains additional data as key-value pairs. Keys are arbitrary, and values can be strings, integers, floats, booleans, objects, arrays, or null.
     * - ``id*``
       - string 🆁
       - ID of the added object. 
     * - ``meta``
       - object
       - Metadata.  

.. _add_objects_response_example: 

.. rubric:: Response example

.. code::

 {
  "card": 3,
  "created_date": "2025-06-09T16:00:12+00:00",
  "modified_date": "2025-06-09T16:00:12+00:00",
  "source_photo_name": "face1.jpg",
  "source_photo": "http://<findface-ip:port>/uploads/cards/Ad/3/face_face1_YB9Eep.jpg",
  "thumbnail": "http://<findface-ip:port>/uploads/cards/G0/3/face_face1_thumbnail_RNeQrf.jpg",
  "frame_coords_left": 722,
  "frame_coords_top": 31,
  "frame_coords_right": 801,
  "frame_coords_bottom": 132,
  "active": true,
  "features": {},
  "id": "4696237533220385428",
  "meta": {}
 }
 
Useful requests
--------------------------

.. code::

  GET /objects/bodies/
  POST /objects/bodies/
  GET /objects/bodies/{id}/
  DELETE /objects/bodies/{id}/
  PATCH /objects/bodies/{id}/
  GET /objects/cars/
  POST /objects/cars/
  GET /objects/cars/{id}/
  DELETE /objects/cars/{id}/
  PATCH /objects/cars/{id}/
  GET /objects/faces/
  POST /objects/faces/
  GET /objects/faces/{id}/
  DELETE /objects/faces/{id}/
  PATCH /objects/faces/{id}/