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.

filter.child_id

Array<String>

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

filter.parent_id

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_id

Array<String>

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

filter.class_id

Array<String>

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

filter.id

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.

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_id": [
            "66c05eec7e8a9b00113f341f",
            "66a8972a71ca890012634a03" // parent objects ID
        ],
        "child_id": [
            "66cba96a8bce1b00111a8bb3",
            "66cbb1268bce1b00111a8bc0"
        ], // child objects ID
        "state_id": [
            1,
            3,
            "58ff5f454815650157a6a62f"
        ], // object state ID
        "class_id": [
            "5926a84355687d6bb793dd88",
            "5926a84355687d6bb793dd9c"
        ], // object class ID
        "id": [
            11,
            14,
            "629709900618240e2b83a18e",
            "626f935fbad91064e16e57b7",
            "626ed4bcbad91064e16e521a"
        ], // object ID
        "tags": [
            "63c6b25aee2fca5eb640456c",
            "6401bbb8b5208c0a9aad17cc"
        ] // tag ID
    },
    "fields": [
        "name",
        "class_id",
        "state_id"
    ],  // names of included fields
    "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_id": [1, 2, 3], //string|number
        "class_id": [], //string|number
        "id": [],  //string|number
        "tags": [] //string
    },
    "fields": [
        "name",
        "class_id",
        "state_id"
    ],

    "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_id": [1, 2, 3], //string|number
        "class_id": [], //string|number
        "id": [],  //string|number
        "tags": [] //string
    },
    "fields": [
        "name",
        "class_id",
        "state_id"
    ],

    "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_id": [1, 2, 3], //string|number
        "class_id": [], //string|number
        "id": [],  //string|number
        "tags": [] //string
    },
    "fields": [
        "name",
        "class_id",
        "state_id"
    ],

    "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_id": [1, 2, 3], //string|number
        "class_id": [], //string|number
        "id": [],  //string|number
        "tags": [] //string
    },
    "fields": [
        "name",
        "class_id",
        "state_id"
    ],

    "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_id": 8,
            "state_id": 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",
            "id": "626f9369033ee864af76d9d3"
        },
        ...
    ]
}