Skip to content

API reference / RivetMSP

Relationships

GET /relationships Bearer token or API key

Links of one record (outgoing, referenced by, and what depends on it)

Returns the explicit links (entity_links) and read-only derived rows from the older link tables (asset documents, software licences, service assets, ...) for one record, plus a transitive "impact" list (what depends on it, up to three levels, cycle safe). Results are limited to records the caller's role and client access allow.

Parameters

NameInTypeDescription
typerequiredquerystring (asset | software | vendor | document | kb_article | service | network | domain)
idrequiredqueryinteger

Example request

curl "https://YOUR-HOST/api/v1/relationships?type=1&id=1" \
  -H "Authorization: Bearer $TOKEN"
import requests

response = requests.get(
    "https://YOUR-HOST/api/v1/relationships",
    headers={"Authorization": f"Bearer {TOKEN}"},
    params={"type":1,"id":1},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/relationships?type=1&id=1", {
  method: "GET",
  headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/relationships?type=1&id=1");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Relationships of the record

FieldTypeDescription
record object
record.type string
record.id integer
record.name string
record.client_id integer
record.archived boolean
outgoing array of object
outgoing[].link_id integer Null for derived rows
outgoing[].derived boolean
outgoing[].source string
outgoing[].link_type string
outgoing[].note string
outgoing[].created_at string
outgoing[].to object
outgoing[].to.type string
outgoing[].to.id integer
outgoing[].to.name string
outgoing[].to.client_id integer
outgoing[].to.archived boolean
outgoing[].from object
outgoing[].from.type string
outgoing[].from.id integer
outgoing[].from.name string
outgoing[].from.client_id integer
outgoing[].from.archived boolean
referenced_by array of object
referenced_by[].link_id integer Null for derived rows
referenced_by[].derived boolean
referenced_by[].source string
referenced_by[].link_type string
referenced_by[].note string
referenced_by[].created_at string
referenced_by[].to object
referenced_by[].to.type string
referenced_by[].to.id integer
referenced_by[].to.name string
referenced_by[].to.client_id integer
referenced_by[].to.archived boolean
referenced_by[].from object
referenced_by[].from.type string
referenced_by[].from.id integer
referenced_by[].from.name string
referenced_by[].from.client_id integer
referenced_by[].from.archived boolean
impact array of object
impact[].type string
impact[].id integer
impact[].name string
impact[].client_id integer
impact[].depth integer
impact[].via string
Example response
json
{
    "record": {
        "type": "string",
        "id": 1,
        "name": "string",
        "client_id": 1,
        "archived": true
    },
    "outgoing": [
        {
            "link_id": 1,
            "derived": true,
            "source": "string",
            "link_type": "string",
            "note": "string",
            "created_at": "string",
            "to": {
                "type": null,
                "id": null,
                "name": null,
                "client_id": null,
                "archived": null
            },
            "from": {
                "type": null,
                "id": null,
                "name": null,
                "client_id": null,
                "archived": null
            }
        }
    ],
    "referenced_by": [
        {
            "link_id": 1,
            "derived": true,
            "source": "string",
            "link_type": "string",
            "note": "string",
            "created_at": "string",
            "to": {
                "type": null,
                "id": null,
                "name": null,
                "client_id": null,
                "archived": null
            },
            "from": {
                "type": null,
                "id": null,
                "name": null,
                "client_id": null,
                "archived": null
            }
        }
    ],
    "impact": [
        {
            "type": "string",
            "id": 1,
            "name": "string",
            "client_id": 1,
            "depth": 1,
            "via": "string"
        }
    ]
}

400Bad request

FieldTypeDescription
error string

404Resource not found

FieldTypeDescription
error string
POST /relationships Bearer token or API key

Link two records

Needs change access to the source record's module and view access to the target's. Both records must be in the same client unless one is kept in no client (a global vendor or KB article).

Request body (application/json, required)

FieldTypeDescription
src_typerequired string (asset | software | vendor | document | kb_article | service | network | domain)
src_idrequired integer
dst_typerequired string (asset | software | vendor | document | kb_article | service | network | domain)
dst_idrequired integer
link_type string (depends_on | runs_on | supported_by | documented_by | related)
note string

Example request

curl -X POST "https://YOUR-HOST/api/v1/relationships" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"src_type":"asset","src_id":1,"dst_type":"asset","dst_id":1,"link_type":"depends_on","note":"string"}'
import requests

response = requests.post(
    "https://YOUR-HOST/api/v1/relationships",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={
        "src_type": "asset",
        "src_id": 1,
        "dst_type": "asset",
        "dst_id": 1,
        "link_type": "depends_on",
        "note": "string"
    },
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/relationships", {
  method: "POST",
  headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
      "src_type": "asset",
      "src_id": 1,
      "dst_type": "asset",
      "dst_id": 1,
      "link_type": "depends_on",
      "note": "string"
  }),
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/relationships");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => '{"src_type":"asset","src_id":1,"dst_type":"asset","dst_id":1,"link_type":"depends_on","note":"string"}',
]);
$data = json_decode(curl_exec($ch), true);

Responses

201Created

FieldTypeDescription
link_id integer
Example response
json
{
    "link_id": 1
}

400Bad request

FieldTypeDescription
error string

403Authenticated but not permitted

FieldTypeDescription
error string

404Resource not found

FieldTypeDescription
error string

409Already linked that way

FieldTypeDescription
error string

422Different clients, or a record linked to itself

FieldTypeDescription
error string
DELETE /relationships/{id} Bearer token or API key

Remove a link (derived rows cannot be removed here)

Parameters

NameInTypeDescription
idrequiredpathinteger

Example request

curl -X DELETE "https://YOUR-HOST/api/v1/relationships/1" \
  -H "Authorization: Bearer $TOKEN"
import requests

response = requests.delete(
    "https://YOUR-HOST/api/v1/relationships/1",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/relationships/1", {
  method: "DELETE",
  headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/relationships/1");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Success

FieldTypeDescription
ok boolean
Example response
json
{
    "ok": true
}

403Authenticated but not permitted

FieldTypeDescription
error string

404Resource not found

FieldTypeDescription
error string