Get references (API v2)

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

Request that returns references 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/getRefs

Permissions

referencePermissions

Body parameters

Parameter Type Description

filter

Object

Filter applied to the list of references. You can find more on the Search page.

filter.owner_ids

Array<String>

Array of user IDs. This request will include all references whose targets are owned by specified users.

filter.target_ids

Array<String>

Array of object IDs. This request will include all references that target specified objects.

filter.ids

Array<String>

Array of reference IDs that should be included in the response.

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 references in the system and include the following fields:

  • target,

  • owner,

  • client_data,

  • id,

  • entityType.

{
    "filter": {
        "owner_ids": [
            "66c05eec7e8a9b00113f341f",
            "66a8972a71ca890012634a03"
        ],
        "target_ids": [
            "66cba96a8bce1b00111a8bb3",
            "66cbb1268bce1b00111a8bc0"
        ],
        "ids": [
            1,
            3,
            "58ff5f454815650157a6a62f"
        ],
    },
    "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/getRefs

curl -X POST $url -u $login:$password \
    -H "Content-Type: application/json" \
    -d @- <<EOF
{
    "filter": {
        "owner_ids": [
            "66c05eec7e8a9b00113f341f",
            "66a8972a71ca890012634a03"
        ],
        "target_ids": [
            "66cba96a8bce1b00111a8bb3",
            "66cbb1268bce1b00111a8bc0"
        ],
        "ids": [
            1,
            3,
            "58ff5f454815650157a6a62f"
        ],
    },
    "limit": 5,
    "offset": 5
}
EOF
let login = <...>
let password = <...>
let saymonHostname = <...>
let path = "/node/api/v2/getRefs";
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": {
        "owner_ids": [
            "66c05eec7e8a9b00113f341f",
            "66a8972a71ca890012634a03"
        ],
        "target_ids": [
            "66cba96a8bce1b00111a8bb3",
            "66cbb1268bce1b00111a8bc0"
        ],
        "ids": [
            1,
            3,
            "58ff5f454815650157a6a62f"
        ],
    },
    "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/getRefs";
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": {
        "owner_ids": [
            "66c05eec7e8a9b00113f341f",
            "66a8972a71ca890012634a03"
        ],
        "target_ids": [
            "66cba96a8bce1b00111a8bb3",
            "66cbb1268bce1b00111a8bc0"
        ],
        "ids": [
            1,
            3,
            "58ff5f454815650157a6a62f"
        ],
    },
    "limit": 5,
    "offset": 5
});

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

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

body = {
    "filter": {
        "owner_ids": [
            "66c05eec7e8a9b00113f341f",
            "66a8972a71ca890012634a03"
        ],
        "target_ids": [
            "66cba96a8bce1b00111a8bb3",
            "66cbb1268bce1b00111a8bc0"
        ],
        "ids": [
            1,
            3,
            "58ff5f454815650157a6a62f"
        ],
    },
    "limit": 5,
    "offset": 5
}

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

Response

{
    "count": 1264,
    "items": [
        {
            "target": "67ffac13bc35cc002f11e11d",
            "owner": "62d7e58056d203149a08001b",
            "client_data": "{\"headlinePropIds\":[],\"custom_style\":{\"zIndex\":176,\"left\":\"514px\",\"top\":\"42px\",\"width\":\"300px\",\"height\":\"200px\"}}",
            "id": "67ffac1fbc35cc002f11e126",
            "entityType": 9
        }
        ...
    ]
}