.. _api_cards: Record ======================== .. _list_human_cards: List records ------------------------------ To retrieve a list of records of individuals, use the following method: .. code:: GET /cards/humans/ .. tip:: To retrieve a list of vehicle records, use ``/cards/cars/`` instead of ``/cards/humans/``. The REQUEST contains the QUERY-STRING PARAMETERS. The list of all available parameters can be found at ``http:///api-docs``. You can use this method to :ref:`search for faces and bodies ` in the system. .. rubric:: CURL example .. code:: curl -X GET "http:///cards/humans/?looks_like=detection:cf4ffvmv54rotim9jt60" \ -H "Authorization: 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 `. :ref:`Example `. .. note:: `*` – means required parameters. 🆁 – read only. .. _list_cards_response_parameters: +--------------------------------------+-------------------+--------------------------------------------------------------------+ | Name | Type | Description | +======================================+===================+====================================================================+ | ``id*`` | integer 🆁 | Record ID. | +--------------------------------------+-------------------+--------------------------------------------------------------------+ | ``active`` | boolean | ``true`` if the record is active. | +--------------------------------------+-------------------+--------------------------------------------------------------------+ | ``created_date*`` | date-time 🆁 | Timestamp indicating when the record was created. | +--------------------------------------+-------------------+--------------------------------------------------------------------+ | ``modified_date*`` | date-time 🆁 | Timestamp indicating when the record was last updated. | +--------------------------------------+-------------------+--------------------------------------------------------------------+ | ``name*`` | string | Record name. | | | | | | | | Constraints: Min 1┃Max 256 chars. | +--------------------------------------+-------------------+--------------------------------------------------------------------+ | ``comment`` | string | Extended description. | | | | | | | | Constraints: Min 0┃Max 2048 chars. | +--------------------------------------+-------------------+--------------------------------------------------------------------+ | ``watch_lists*`` | array of integers | Array of related watch list IDs. | +--------------------------------------+-------------------+--------------------------------------------------------------------+ | ``looks_like*`` | object | Present in the response only if the ``looks_like`` parameter | | | | is specified in the ``GET /cards/humans/`` request. | | | | | | | | Contains information about the most similar object in the record. | +---------+----------------------------+-------------------+--------------------------------------------------------------------+ | | ``confidence*`` | number | Value of the ``looks_like_confidence`` parameter. | | | | | | | | | | Constraints: Min 0┃Max 1. | + +----------------------------+-------------------+--------------------------------------------------------------------+ | | ``collection*`` | string┃null | Name of the object collection where the matched object was | | | | | found (e.g., ``face_objects`` for the face collection). | + +----------------------------+-------------------+--------------------------------------------------------------------+ | | ``matched_object*`` | string┃null | ID of the matched object in the record. | +---------+----------------------------+-------------------+--------------------------------------------------------------------+ | ``meta`` | object | Metadata. | +--------------------------------------+-------------------+--------------------------------------------------------------------+ | ``looks_like_confidence*`` | number 🆁 | Present in the response if the ``looks_like`` parameter is | | | | specified in the ``GET /cards/humans/`` request. | | | | | | | | Indicates the similarity score between two feature vectors in | | | | the database: the feature vector of the object being searched for | | | | via the ``looks_like`` parameter and the feature vector of the | | | | matched object in the record. | | | | | | | | The value of the ``looks_like_confidence`` parameter is used when | | | | filtering results by the similarity score if the ``threshold`` | | | | parameter is specified. | +--------------------------------------+-------------------+--------------------------------------------------------------------+ | ``face_objects*`` | integer 🆁 | Total number of face objects in the record. | +--------------------------------------+-------------------+--------------------------------------------------------------------+ | ``body_objects*`` | integer 🆁 | Total number of body objects in the record. | +--------------------------------------+-------------------+--------------------------------------------------------------------+ | ``face_cluster*`` | integer 🆁 | ID of the face cluster that matched the record. | +--------------------------------------+-------------------+--------------------------------------------------------------------+ | ``body_cluster*`` | integer 🆁 | ID of the body cluster that matched the record. | +--------------------------------------+-------------------+--------------------------------------------------------------------+ .. _search_example: .. rubric:: Response example .. code:: { "next_page": null, "prev_page": null, "results": [ { "id": 1, "active": true, "created_date": "2025-01-17T07:43:56.363330Z", "modified_date": "2025-01-17T11:56:42.496871Z", "name": "Angelina Jolie", "comment": "actor", "watch_lists": [ 2 ], "looks_like": { "confidence": 0.8078, "collection": "face_objects", "matched_object": "4493493039043981648" }, "meta": {}, "looks_like_confidence": 0.8078, "face_objects": 1, "body_objects": 0, "face_cluster": 11, "body_cluster": null } ] } .. _create_new_record: Create a new record ----------------------- To create a new record for individuals, use the following method: .. code:: POST /cards/humans/ .. tip:: To create a vehicle record, use ``/cards/cars/`` instead of ``/cards/humans/``. 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 created record will be active. * - ``name*`` - string - Record name. Constraints: Min 1┃Max 256 chars. * - ``comment`` - string - Extended description. Constraints: Min 0┃Max 2048 chars. * - ``watch_lists*`` - array of integers - Array of related watch list IDs. * - ``meta`` - object - Metadata represented as an object with string keys and arbitrary values. .. 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", "watch_lists": [ 0 ], "meta": {} } For example, you can send these parameters: .. code:: { "active": true, "name": "new card", "comment": "sample", "watch_lists": [ 1 ] } .. rubric:: CURL example .. code:: curl -X POST "http:///cards/humans/" \ -H "Authorization: Token " \ -H "Content-Type: application/json" \ -d '{"active":true,"name":"new card","comment":"sample","watch_lists":[1]}' If the response is successful (Created: 201), it returns a JSON object that contains :ref:`parameters `. :ref:`Example `. .. _post_card_response_example: .. rubric:: Response example .. code:: { "id": 24, "active": false, "created_date": "2025-07-21T15:26:52.435522Z", "modified_date": "2025-07-21T15:26:52.435560Z", "name": "new card", "comment": "sample", "watch_lists": [ 1 ], "meta": {}, "face_objects": 0, "body_objects": 0, "face_cluster": null, "body_cluster": null } Useful requests -------------------------- .. code:: GET /cards/cars/ POST /cards/cars/ GET /cards/cars/{id}/ DELETE /cards/cars/{id}/ PATCH /cards/cars/{id}/ GET /cards/cars/count/ GET /cards/humans/ POST /cards/humans/ GET /cards/humans/{id}/ DELETE /cards/humans/{id}/ PATCH /cards/humans/{id}/ GET /cards/humans/count/