Tool references
List what references a set of tools
Returns, for each tool referenceId, the agents and skills in the project that hold it. This endpoint is read-only, and you can use it to warn before a delete, because deleting a tool detaches it from everything listed here. projectId is required, because the authorization middleware reads it to scope the request.
GET
/
tool-references
List what references a set of tools
curl --request GET \
--url https://api-trial.cognigy.ai/v1/tool-references \
--header 'X-API-Key: <api-key>'import requests
url = "https://api-trial.cognigy.ai/v1/tool-references"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api-trial.cognigy.ai/v1/tool-references', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-trial.cognigy.ai/v1/tool-references",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api-trial.cognigy.ai/v1/tool-references"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api-trial.cognigy.ai/v1/tool-references")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-trial.cognigy.ai/v1/tool-references")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"items": [
{
"holders": [
{
"id": "507f1f77bcf86cd799439011",
"kind": "agent",
"name": "Support Bot",
"referenceId": "550e8400-e29b-41d4-a716-446655440000"
}
],
"toolReferenceId": "550e8400-e29b-41d4-a716-446655440000"
}
],
"total": 2
}{
"detail": "request body validation failed",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
],
"instance": "/v1/{resource}",
"status": 400,
"title": "Bad Request",
"traceId": "api--a4d2f126-bec4-4544-a049-7c0cf08524ed",
"type": "about:blank"
}{
"detail": "access denied: insufficient permissions",
"instance": "/v1/{resource}/{id}",
"status": 403,
"title": "Forbidden",
"traceId": "api--a4d2f126-bec4-4544-a049-7c0cf08524ed",
"type": "about:blank"
}{
"detail": "internal server error",
"instance": "/v1/{resource}",
"status": 500,
"title": "Internal Server Error",
"traceId": "api--a4d2f126-bec4-4544-a049-7c0cf08524ed",
"type": "about:blank"
}Authorizations
[Production] API key for production authentication
Query Parameters
A comma-separated list of tool referenceId values, with at most 100 distinct values. Repeated values collapse and don't count against the limit.
The unique identifier for the project.
Response
OK
Show child attributes
Show child attributes
Total is the number of DISTINCT holders across every item — how many agents and skills a delete of all the requested tools would detach them from. It is deliberately none of the two things it could easily have been:
len(Items), which is what it used to be. Every requested id gets an entry, so that number is identical to Items' own length and carries no information at all, while theexample:"2"beside it suggested a holder count. Redundant and misleading at once.- the SUM of each item's holders, which double-counts: one agent holding three of the requested tools would make "delete 3 tools, detaching from 1 agent" report 3.
Distinct is the number a delete confirmation wants, and it is correct for
one requested tool and for many. Per-tool counts are already available as
items[i].holders.length, so nothing is lost by not summing.
Example:
2
⌘I
List what references a set of tools
curl --request GET \
--url https://api-trial.cognigy.ai/v1/tool-references \
--header 'X-API-Key: <api-key>'import requests
url = "https://api-trial.cognigy.ai/v1/tool-references"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api-trial.cognigy.ai/v1/tool-references', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-trial.cognigy.ai/v1/tool-references",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api-trial.cognigy.ai/v1/tool-references"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api-trial.cognigy.ai/v1/tool-references")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-trial.cognigy.ai/v1/tool-references")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"items": [
{
"holders": [
{
"id": "507f1f77bcf86cd799439011",
"kind": "agent",
"name": "Support Bot",
"referenceId": "550e8400-e29b-41d4-a716-446655440000"
}
],
"toolReferenceId": "550e8400-e29b-41d4-a716-446655440000"
}
],
"total": 2
}{
"detail": "request body validation failed",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
],
"instance": "/v1/{resource}",
"status": 400,
"title": "Bad Request",
"traceId": "api--a4d2f126-bec4-4544-a049-7c0cf08524ed",
"type": "about:blank"
}{
"detail": "access denied: insufficient permissions",
"instance": "/v1/{resource}/{id}",
"status": 403,
"title": "Forbidden",
"traceId": "api--a4d2f126-bec4-4544-a049-7c0cf08524ed",
"type": "about:blank"
}{
"detail": "internal server error",
"instance": "/v1/{resource}",
"status": 500,
"title": "Internal Server Error",
"traceId": "api--a4d2f126-bec4-4544-a049-7c0cf08524ed",
"type": "about:blank"
}