Parameters

You can add a query string just after the endpoint, preceded by a question mark. This provides a string of information that will specify special parameters for your query. In this chapter, you will find a description of the URL parameters available for specific methods to be included within a path.


Fields

This parameter is used to specify only desired object fields in the query. Null values are skipped, unless explicitly requested.


If query has no fields parameter specified:

  • GET method will return all attributes of an object except those set to Null,
  • POST method will show only id fields,
  • PATCH method will not return any fields.

When using fields parameter with no value (fields=):

  • GET method will return id field only,
  • POST and PATCH will not return any fields.

Duplicated fields are ignored, e.g., fields=id,name,name,protocol will be treated like fields=id,name,protocol.


The example below utilizes the fields and filter parameters to narrow down the result to servers that include the string test in the name field, returning only the id, name and protocol fields in the response:


GET https://10.0.0.0/api/v2/server?fields=id,name,protocol&filter=name.match(test)

Filter

Note

Please note that certain filters are applied automatically depending on the user’s role.

This parameter narrows out the result with available additions:

  • .in() - include possible attribute values,
  • .iin() - case insensitive version of .in(),
  • .contains() - include possible fields containing specified values, only applies to arrays (e.g., account?filter=server_ids.contains(345)),

Note

  • When using .in(), .iin(), and .contains(), we can input multiple values with a comma as a separator (e.g., server?filter=protocol.in(ssh,rdp,vnc), account?filter=server_ids.contains(1,2,3)). In this situation, at least one of the given conditions must be met.
  • We can also use multiple conditions separated with comma (e.g., server?filter=server_ids.contains(1),server_ids.contains(2)). In such cases, all given conditions must be met. This rule applies to all parameters.

  • .match() - include a regular expression to be searched in field values,
  • .imatch() - case insensitive version of .match(),
  • .eq() - equal (name.eq(foo)),
  • .ieq() - case insensitive version of  .eq(),
  • .ne() - not equal,
  • .ine() - case insensitive version of .ne(),
  • .lt() - less than,
  • .le() - less or equal,
  • .gt() - greater than,
  • .ge() - greater than or equal,
  • <attribute> - filter objects based on attributes of type boolean set to true,
  • !<attribute> - filter objects based on attributes of type boolean set to false,

Note

The example filter filter=protocol.eq(ssh),!legacy_crypto,tls_enabled filters out objects with the protocol equal to ssh, boolean type attribute legacy_crypto set to false and boolean type attribute tls_enabled set to true.


  • .isnull() - filter objects with empty values in specified fields (e.g., description.isnull()),
  • .isempty() - filter objects with empty values in specified fields, only applies to arrays.

Note

Every filter can be negated with <!>. For instance, the query filter=!protocol.eq(ssh) will skip all objects with the protocol attribute set to ssh. This example is equivalent of protocol.ne(ssh).

Note

While using DELETE method:

  • negation <!> cannot be used,
  • for safety reasons, at least one unique filter value must be used in the query (e.g., id, name),
  • if an object does not have a unique attribute, uniqueness is determined based on a set of attributes (e.g., filter=account_id.eq(123456),safe_id.eq(345567),listener_id.eq(789012)).

Search in “all” attributes

The special attribute all. enables searching for a specified value in all attributes of type number and string.

Note

Only .match() and .imatch() methods can be used on this special attribute.

The example below searches for the string rdp in all eligible attributes of the server objects. As a result, it will return all servers that have the string rdp included in fields such as name, protocol, description, or reason.

GET https://10.0.0.0/api/v2/server?filter=all.imatch(rdp)

Order

This parameter specifies the order of returned data.

Note

You can reverse the order with an exclamation mark <!>.

Example below will return all servers id, name and protocol fields, sorted first by protocol, and next by reverse id order:


Example request

GET https://10.0.0.0/api/v2/server?fields=id,name,protocol&order=protocol,!id

Response

{
     "result": "success",
     "server": [
         {
             "id": "918734323983581188",
             "name": "RDP_server_2",
             "protocol": "rdp"
         },
         {
             "id": "918734323983581187",
             "name": "RDP_server",
             "protocol": "rdp"
         },
         {
             "id": "918734323983581186",
             "name": "windows.example.org",
             "protocol": "rdp"
         },
         {
             "id": "918734323983581189",
             "name": "SSH_server",
             "protocol": "ssh"
         },
         {
             "id": "918734323983581185",
             "name": "linux.example.org",
             "protocol": "ssh"
         }
     ]
 }

Offset

This parameter is used to exclude from a response the first N items of a resource collection. Example below skips first 5 objects on the query response:

GET https://10.0.0.0/api/v2/user?offset=5

For predictable results, use this parameter in conjunction with order parameter.


Limit

This query parameter specifies the number of instances that a single response contains. Example below limits the list of returned objects to 10 (by ID order):

GET https://10.0.0.0/api/v2/user?fields=id,name&order=id&filter=role.eq(user)&limit=10

Note

  • If the limit is not specified in a query, the API will automatically return 1000 records by default.
  • Setting the limit value above 1000 results in a Bad Request error.

Debug

This parameter is used to diagnose a query. Example below returns query with debugging data:

GET https://10.0.0.0/api/v2/server?fields=id,name,protocol&order=protocol,!id&debug

{
    "result": "success",
    "server": [
        {
            "id": "918734323983581188",
            "name": "RDP_server_2",
            "protocol": "rdp"
        },
        {
            "id": "918734323983581187",
            "name": "RDP_server",
            "protocol": "rdp"
        },
        {
            "id": "918734323983581186",
            "name": "windows.example.org",
            "protocol": "rdp"
        },
        {
            "id": "918734323983581189",
            "name": "SSH_server",
            "protocol": "ssh"
        },
        {
            "id": "918734323983581185",
            "name": "linux.example.org",
            "protocol": "ssh"
        }
    ],
    "debug": {
        "timings": {
            "total start": null,
            "receive start": null,
            "receive duration": "0.000142s",
            "endpoint_verify start": null,
            "endpoint_verify duration": "0.000003s",
            "endpoint_execute start": null,
            "database_request (SELECT) start": null,
            "database_request (SELECT) duration": "0.001976s",
            "endpoint_execute duration": "0.002087s",
            "total duration": "0.008025s"
        }
    }
}

Total_count

This parameter returns the total number of objects, taking into account the filters applied in the query, but at the same time ignoring limit and offset parameters. In the case of large amounts of objects it can be expensive to use.


Estimated_total_count

This parameter can be inaccurate, so it is useful just to estimate quantities. It is much less expensive to use than total_count, includes deleted and hidden objects, ignores filter parameters and is only available for superadmin role.


Reveal

This parameter enables to view objects with the following states:

  • active,
  • removed,
  • visible,
  • hidden,
  • all.

By default reveal is set to active and visible states (?reveal=active,visible). If we do not specify it as active or removed (e.g., ?reveal=visible) it will return only active objects.


The same situation occurs in the case of visible and hidden pair of parameters. If we do not specify reveal as  visible or hidden, it will by default take the visible value and return only visible objects.