Relationships
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 department access allow.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| typerequired | query | string (asset | software | vendor | document | kb_article | service | network | domain) | |
| idrequired | query | integer |
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
| Field | Type | Description |
|---|---|---|
| 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
{
"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
| Field | Type | Description |
|---|---|---|
| error | string |
404Resource not found
| Field | Type | Description |
|---|---|---|
| error | string |
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 department unless one is kept in no department (a global vendor or KB article).
Request body (application/json, required)
| Field | Type | Description |
|---|---|---|
| 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
| Field | Type | Description |
|---|---|---|
| link_id | integer |
Example response
{
"link_id": 1
}
400Bad request
| Field | Type | Description |
|---|---|---|
| error | string |
403Authenticated but not permitted
| Field | Type | Description |
|---|---|---|
| error | string |
404Resource not found
| Field | Type | Description |
|---|---|---|
| error | string |
409Already linked that way
| Field | Type | Description |
|---|---|---|
| error | string |
422Different departments, or a record linked to itself
| Field | Type | Description |
|---|---|---|
| error | string |
Remove a link (derived rows cannot be removed here)
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| idrequired | path | integer |
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
| Field | Type | Description |
|---|---|---|
| ok | boolean |
Example response
{
"ok": true
}
403Authenticated but not permitted
| Field | Type | Description |
|---|---|---|
| error | string |
404Resource not found
| Field | Type | Description |
|---|---|---|
| error | string |