Search and Search Result Export 
-------------------------------

For an API call that carries out a search, a POST payload in JSON format is added.

.. tabularcolumns:: |p{1.5cm}|p{1cm}|p{3cm}|p{5cm}|p{5cm}|

+-----------+-------+--------------------------+-------------------------+--------------------------------------+
| Task      | Call  | URL                      | Parameters              | Payload                              |
+===========+=======+==========================+=========================+======================================+
| Search    | POST  | /api/tool/Search/        | format=json             | {"query":"[query]"}                  |
|           |       |                          |                         |                                      |
|           |       |                          | hierarchy=[hierarchy]   |                                      |
+-----------+-------+--------------------------+-------------------------+--------------------------------------+

The value of ``[query]`` follows Search syntax, for example:

::

   {"query":"data/Countries with country_name contains King"}

While the default search direction is down, a second parameter can be added
to ``[query]`` to indicate the hierarchy direction
to search. These are enabled by adding a value ``true``:

* ``hierarchy_paths`` - up the hierarchy
* ``hierarchy_shallow`` - at the local hierarchy
* ``hierarchy_all`` - up and down the hierarchy

For example, if the user making the API call is at ``sys.hcs``, then
a call payload like:

::

   {"query":"relation/Bundle with name is 'HcsBase' ", "hierarchy_paths":true}

will also search up the hierarchy path.

The parameter ``filter_hierarchy`` can also be used to filter the hierarchy of search results.
Specifying a hierarchy to which the user has no access will return a Permission Denied error.

.. note::

   * If for both ``hierarchy=sys.hcs`` and ``filter_hierarchy=sys.hcs.CSP`` for example are used, then
     ``filter_hierarchy=sys.hcs.CSP`` takes precedence.
   * If for neither ``hierarchy=sys.hcs`` nor ``filter_hierarchy=sys.hcs.CSP`` for example are used, then
     the user's hierarchy is applied.

The Request payload can also be a GET parameter, for example:

.. tabularcolumns:: |p{1.5cm}|p{1cm}|p{3cm}|p{5cm}|p{5cm}|

+--------+------+-------------------+------------------------------+-----------------------------------+
| Task   | Call | URL               | Parameters                   | Response                          |
+========+======+===================+==============================+===================================+
| Search | GET  | /api/tool/Search/ | format=json                  | JSON format of the search result. |
|        |      |                   |                              |                                   |
|        |      |                   | hierarchy=[hierarchy]        |                                   |
|        |      |                   |                              |                                   |
|        |      |                   | filter_hierarchy=[hierarchy] |                                   |
|        |      |                   |                              |                                   |
|        |      |                   | query=[url_query]            |                                   |
+--------+------+-------------------+------------------------------+-----------------------------------+

The value of ``[url_query]`` is URL encoded string, for example:

::

   data/Countries%20with%20country_name%20contains%20King


Furthermore, the ``meta`` property of the schema in the response to ``/api/tool/Search/``    
contains action details for the export of search results.
This includes the URL for the data export POST request:

::

   /api/export/export_data/?url=/api/tool/Search/

as well as the URL:

::

   /api/view/ExportData/add
   
which has a schema that lists the data export data type choices
that will be used as a parameter to the POST call.




.. |VOSS Automate| replace:: VOSS Automate
.. |Unified CM| replace:: Unified CM