.. _search_objects:

Method: Search for Objects
--------------------------

Description
~~~~~~~~~~~

Search in unencrypted meta data to locate objects.

URL Syntax
~~~~~~~~~~

/api/{version}/find

HTTP Method
~~~~~~~~~~~

GET

Successful HTTP Response
~~~~~~~~~~~~~~~~~~~~~~~~

200

Parameters
~~~~~~~~~~

+----------------+------------------+----------------+--------+-----------+------------------+
| Parameter name |   Description    | Parameter type |  Type  | Mandatory |     Comment      |
+================+==================+================+========+===========+==================+
| X-Http-Token   | StoredSafe token | HTTP Header    | String | :sup:`1)` | Preferred method |
+----------------+------------------+----------------+--------+-----------+------------------+
| token          | StoredSafe token | JSON-encoded   | String | :sup:`1)` | Legacy method    |
+----------------+------------------+----------------+--------+-----------+------------------+
| needle         | Search string    | URL-parameter  | String | Yes       | Case insensitive |
+----------------+------------------+----------------+--------+-----------+------------------+

\*) One of the methods (HTTP Header or JSON-encoded) is required.

Response Attributes
~~~~~~~~~~~~~~~~~~~

+---------------------------------+----------------------------------------------------------------+---------+
|            Attribute            |                          Description                           |  Type   |
+=================================+================================================================+=========+
| CALLINFO.errorcodes             | Number of errors                                               | Integer |
+---------------------------------+----------------------------------------------------------------+---------+
| CALLINFO.errors                 | Number of errors                                               | Integer |
+---------------------------------+----------------------------------------------------------------+---------+
| CALLINFO.general                | Information                                                    | Array   |
+---------------------------------+----------------------------------------------------------------+---------+
| CALLINFO.handler                | Handler used                                                   | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| CALLINFO.status                 | SUCCESS or FAIL                                                | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| CALLINFO.message                | Message from handler (if successful)                           | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| CALLINFO.token                  | StoredSafe token to be used in subsequent calls                | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| HEADERS                         | HTTP Headers                                                   | Object  |
+---------------------------------+----------------------------------------------------------------+---------+
| DATA                            | Supplied data in API-call                                      | Object  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT                          | OBJECT entry                                                   | Array   |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.id                       | Object-ID                                                      | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.parentid                 | Parent-ID                                                      | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.templateid               | Template-ID                                                    | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.groupid                  | Vault-ID                                                       | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.status                   | Status (Active, Follows policy)                                | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.objectname               | Name of object                                                 | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.filename                 | Filename (if a file)                                           | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.children                 | Any children                                                   | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.notes                    | Encrypted notes                                                | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.tags                     | Tags associated with the object                                | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.alarmed                  | Should an alarm sound if object is decrypted?                  | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| OBJECT.public                   | Public data (Depends on Template used, see supplied TEMPLATES) | Object  |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES                       | TEMPLATES (Glue) Used templates in the vault                   | Array   |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.id                    | Template-ID                                                    | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.info.id               | Template-ID                                                    | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.info.name             | Name of template                                               | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.info.ico              | Icon used for template                                         | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.info.active           | Active (True/False)                                            | Boolean |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.info.wb               | Use workbench for edit? (Always use "ed" if false.             | Boolean |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.info.ed               | Edit directly? (no subitems)                                   | Boolean |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.info.jp               | Jump to parent on save?                                        | Boolean |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.structure             | Template Structure                                             | Array   |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.structure.translation | Descriptive text (english)                                     | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.structure.type        | Type of element (text, textarea, text-passwdgen, file)         | String  |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.structure.encrypted   | Is field encrypted?                                            | Boolean |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.structure.show        | Show field normally or only in workbench?                      | Boolean |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.structure.policy      | Should field honor Vaults password policy?                     | Boolean |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.structure.alarm       | Should alarm sound if object is decrypted?                     | Boolean |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.structure.opt         | Is this an optional field or is it required to be filled?      | Boolean |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.structure.cc          | Needs to be changed to be considered unseen?                   | Boolean |
+---------------------------------+----------------------------------------------------------------+---------+
| TEMPLATES.structure.nc          | Encrypted fields needs to be clicked to be revealed?           | Boolean |
+---------------------------------+----------------------------------------------------------------+---------+
| PARAMS                          | PARAMS (empty)                                                 | Array   |
+---------------------------------+----------------------------------------------------------------+---------+

Examples
~~~~~~~~

Search thru Vaults and objects this user has at least Read access to, for the string "pfsense".

**Request**

::

    GET /api/1.0/find?needle=pfSense
    x-http-token: your_storedsafe_token

**Response**

::

    HTTP/2 200
    Content-type: application/json; charset=UTF-8
    {
        "CALLINFO": {
            "errorcodes": 0,
            "errors": 0,
            "general": [],
            "handler": "FindHandler",
            "status": "SUCCESS",
            "token": "rotated_storedsafe_token"
        },
        "DATA": {
            "needle": "pfsense",
            "token": "your_storedsafe_token"
        },
        "HEADERS": {
            "Accept": "*/*",
            "Host": "safe.domain.cc",
            "User-Agent": "curl/7.64.1",
            "X-Http-Token": "your_storedsafe_token"
        },
        "OBJECT": [
            {
                "alarmed": false,
                "children": "0",
                "filename": "",
                "groupid": "121",
                "id": "1368",
                "notes": false,
                "objectname": "firewall2.za.example.com",
                "parentid": "0",
                "public": {
                    "host": "firewall2.za.example.com",
                    "info": "The second pfSense fw protecting the ZA branch.",
                    "username": "root"
                },
                "status": "1152",
                "tags": "",
                "templateid": "1"
            }
        ],
        "PARAMS": [],
        "TEMPLATES": [
            {
                "id": "1",
                "info": {
                    "active": true,
                    "ico": "ico_server",
                    "id": "1",
                    "name": "Server",
                    "wb": true
                },
                "structure": [
                    {
                        "alarm": false,
                        "cc": false,
                        "encrypted": false,
                        "fieldname": "host",
                        "nc": false,
                        "opt": false,
                        "policy": false,
                        "show": true,
                        "translation": "Host",
                        "type": "text"
                    },
                    {
                        "alarm": false,
                        "cc": false,
                        "encrypted": false,
                        "fieldname": "username",
                        "log": true,
                        "nc": false,
                        "opt": false,
                        "policy": false,
                        "show": true,
                        "translation": "Username",
                        "type": "text"
                    },
                    .
                    .
                ]
            }
        ]
    }