Posting Versions
----------------

To post a new version of an instance, send a ``POST`` request to the ``/versions`` endpoint. Simply include the object instance, type and the keys that uniquely identify the instance, and Ichno will automatically compare the current state with the previous version, storing any detected changes.

The request body must be a JSON object with the following fields:

Post Struct
^^^^^^^^^^^

In addition to your object instance, you can include other fields to store additional information about the posted version:

.. list-table::
    :widths: 15 15 15 55
    :header-rows: 1

    * - Field
      - Type
      - Required
      - Description
    * - id
      - ``UUID``
      - No **(but recommended)**
      - | The identifier for this version. 
        | This `id` must be generated by the client. It allows the client application to refer to the posted version in an asynchronous scenario, even if it has not been processed by Ichno yet.
    * - type
      - ``string``
      - **Yes**
      - | The type of the instance being registered. 
        | This helps to categorize different instance types (e.g., `user`, `product`) and prevents conflicts between instances with the same key in different types. You can send the table or model name, for example.
    * - keys
      - | ``[string]: string | number | boolean``
        | (Key Value List)
      - **Yes**
      - | Unique identifier of the instance in the client’s system. 
        | Send the IDs of this instance. This is a list to allow sending objects with composite keys.
    * - object
      - ``object``
      - **Yes**
      - | The instance to be registered. 
        | Send the current state of the instance after all changes are applied. Ichno will compare this with the previously registered version and compute all changes.
    * - labels
      - | ``[string]: string | number | boolean``
        | (Key Value List)
      - **No**
      - | Version labels. 
        | Send labels for this version. Labels are additional data for the version but, unlike metadata, these labels can be used as filters. For example, you can send the user ID of the person changing the instance, enabling you to filter all changes made by a specific user.
    * - metadata
      - ``object``
      - No
      - | Additional data for this version. 
        | Use this field to add extra data to your version. The values in this field **cannot** be queried but can be retrieved when needed.