Get objects (API v2)

This is an experimental request and may change in future releases.

Request that returns objects in the system. You can pass filters and other options in the request body to customize the output.

Request

HTTP Request

POST /node/api/v2/getObjects

Permissions

objectPermissions

Body parameters

Parameter Type Description

filter

Object

Filter applied to the list of objects. You can find more on the Search (API v2) page.

filter.child_ids

Array<String>

Array of object IDs. This request will include all objects that have any of the specified objects as children.

filter.parent_ids

Array<String>

Array of object IDs. This request will include all objects that have any of the specified objects as parents.

filter.name

String

Name or part of the name of the object. Case insensitive.

filter.state_ids

Array<String>

Array of state IDs. Links that are currently in these states will be included in the response.

filter.class_ids

Array<String>

Array of class IDs. Links of that class will be included in the response.

filter.ids

Array<String>

Array of link IDs. Links with those IDs will be included in the response.

filter.tags

Array<String>

Array of tag IDs. Links that are tagged with the specified tags will be included in the response.

fields

Array<String>

Names of fields that will be included in the response.

flags

Array<String>

Additional request flags.

System supports the following flags:

- paths – add a path to an object in the response (paths field), - deepParents – special search mode that will return objects that have objects with id specified in the parent_ids field anywhere in their path, not just a direct parent, - withHidden – include hidden objects in the response, - invalidateCacheMode – update Redis for every returned object.

order

Array

Array of fields by which this request sorts the links. By default, the included field is sorted in ascending order. If the field has a ! character before its name, the list will be sorted in descending order.

limit

Integer

Maximum amount of links included in the response.

offset

Integer

How many records this request should skip.

Request body

Request body allows you to configure the output of this request. You can filter and sort the returned objects, specify which fields are returned and use server-side pagination with the limit and offset parameters.

Request body is optional. If the request body is empty, the response will contain all objects in the system and include the following fields:

  • source

  • target

  • class_id

  • state_id

  • last_state_update

  • source_name

  • target_name

  • name

  • id

{
    "filter": {
        "parent_ids": [
            "66c05eec7e8a9b00113f341f",
            "66a8972a71ca890012634a03" // parent objects ID
        ],
        "child_ids": [
            "66cba96a8bce1b00111a8bb3",
            "66cbb1268bce1b00111a8bc0"
        ], // child objects ID
        "state_ids": [
            1,
            3,
            "58ff5f454815650157a6a62f"
        ], // object state ID
        "class_ids": [
            "5926a84355687d6bb793dd88",
            "5926a84355687d6bb793dd9c"
        ], // object class ID
        "ids": [
            11,
            14,
            "629709900618240e2b83a18e",
            "626f935fbad91064e16e57b7",
            "626ed4bcbad91064e16e521a"
        ], // object ID
        "tags": [
            "63c6b25aee2fca5eb640456c",
            "6401bbb8b5208c0a9aad17cc"
        ] // tag ID
    },
    "fields": [
        "name",
        "class_id",
        "state_id"
    ],  // names of included fields
    "flags":[
        "withHidden",
        "paths"
    ],
    "order": [
        "class_id",
        "!id"], // list is sorted by class_id in ascending order, then by id in descending order
    "limit": 5,
    "offset": 5
}

Response

Response contains a list of objects stored in the items array and the number of returned objects in the count field.

The list of returned objects depends on the filters and settings passed in the request body.

Examples

Request

  • Bash

  • JavaScript

  • NodeJS

  • Python

login=<...>
password=<...>
saymon_hostname=<...>
url=https://$saymon_hostname/node/api/v2/getObjects

curl -X POST $url -u $login:$password \
    -H "Content-Type: application/json" \
    -d @- <<EOF
{
    "filter": {
        "source": [
            "66c05eec7e8a9b00113f341f",
            "66a8972a71ca890012634a03" //string|number
        ],
        "target": ["66cba96a8bce1b00111a8bb3", "66cbb1268bce1b00111a8bc0"], //string|number
        "state_ids": [1, 2, 3], //string|number
        "class_ids": [], //string|number
        "ids": [],  //string|number
        "tags": [] //string
    },
    "fields": [
        "name",
        "class_ids",
        "state_ids"
    ],

    "order":["field1","!field2"], //field1 is sorted in ascending order, field2 – in descending
    "limit": 5,
    "offset": 5
}
EOF
let login = <...>
let password = <...>
let saymonHostname = <...>
let path = "/node/api/v2/getObjects";
let auth = "Basic " + btoa(login + ":" + password);

let headers = new Headers();
headers.append("Content-Type", "application/json");
headers.append("Authorization", auth);

let data = JSON.stringify({
    "filter": {
        "source": [
            "66c05eec7e8a9b00113f341f",
            "66a8972a71ca890012634a03" //string|number
        ],
        "target": ["66cba96a8bce1b00111a8bb3", "66cbb1268bce1b00111a8bc0"], //string|number
        "state_ids": [1, 2, 3], //string|number
        "class_ids": [], //string|number
        "ids": [],  //string|number
        "tags": [] //string
    },
    "fields": [
        "name",
        "class_ids",
        "state_ids"
    ],

    "order":["field1","!field2"], //field1 is sorted in ascending order, field2 – in descending
    "limit": 5,
    "offset": 5
});

let requestOptions = {
    method: "POST",
    headers: headers,
    body: data
};

fetch(saymonHostname + path, requestOptions)
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.log("error", error));
const http = require("http");

let login = <...>
let password = <...>
let saymonHostname = <...>
let path = "/node/api/v2/getObjects";
let auth = "Basic " + Buffer.from(login + ":" + password).toString("base64");

let options = {
    "method": "POST",
    "hostname": saymonHostname,
    "headers": {
        "Authorization": auth,
        "Content-Type": "application/json"
    },
    "path": path
};

let req = http.request(options, function (res) {
    let chunks = [];

    res.on("data", function (chunk) {
        chunks.push(chunk);
    });

    res.on("end", function (chunk) {
        let body = Buffer.concat(chunks);
        console.log(body.toString());
    });

    res.on("error", function (error) {
        console.error(error);
    });
});

let data = JSON.stringify({
    "filter": {
        "source": [
            "66c05eec7e8a9b00113f341f",
            "66a8972a71ca890012634a03" //string|number
        ],
        "target": ["66cba96a8bce1b00111a8bb3", "66cbb1268bce1b00111a8bc0"], //string|number
        "state_ids": [1, 2, 3], //string|number
        "class_ids": [], //string|number
        "ids": [],  //string|number
        "tags": [] //string
    },
    "fields": [
        "name",
        "class_ids",
        "state_ids"
    ],

    "order":["field1","!field2"], //field1 is sorted in ascending order, field2 – in descending
    "limit": 5,
    "offset": 5
});

req.write(data);
req.end();
import requests

login = <...>
password = <...>
saymon_hostname = <...>
url = "https://" + saymon_hostname + "/node/api/v2/getObjects"

body = {
    "filter": {
        "source": [
            "66c05eec7e8a9b00113f341f",
            "66a8972a71ca890012634a03" //string|number
        ],
        "target": ["66cba96a8bce1b00111a8bb3", "66cbb1268bce1b00111a8bc0"], //string|number
        "state_ids": [1, 2, 3], //string|number
        "class_ids": [], //string|number
        "ids": [],  //string|number
        "tags": [] //string
    },
    "fields": [
        "name",
        "class_ids",
        "state_ids"
    ],

    "order":["field1","!field2"], //field1 is sorted in ascending order, field2 – in descending
    "limit": 5,
    "offset": 5
}

response = requests.request("POST", url, json=body, auth=(login, password))
print(response.text)

Response

{
    "count": 1264,
    "items": [
        {
            "source": "626f8ffd38f5c964197d1d7d",
            "target": "626f8ffd38f5c964197d1d8d",
            "class_ids": 8,
            "state_ids": 1,
            "last_state_update": 1651479401339,
            "source_name": "192.168.2.3",
            "target_name": "192.168.11.3/255.255.255.255",
            "name": "192.168.2.3 - 192.168.11.3/255.255.255.255",
            "ids": "626f9369033ee864af76d9d3"
        },
        ...
    ]
}