Tools

11 endpoint-uri. Fiecare cale de mai jos este relativă la URL-ul de bază al API-ului și include deja prefixul /api/v1 — vezi convențiile pentru autentificare, paginare, erori și idempotență.

	Endpoint
GET	`/tools`	Lists the organization's tools, newest first, filterable by type, publication state and MCP server
POST	`/tools`	Creates a draft tool, validating the outbound HTTP request configuration for request-making types
GET	`/tools/{tool}`	Returns one tool with its parameter schema and provider configuration
PUT	`/tools/{tool}`	Updates a tool draft with PATCH semantics, re-running the HTTP config validator when relevant
DELETE	`/tools/{tool}`	Deletes a tool from the organization
POST	`/tools/{tool}/duplicate`	Copies a tool into a new unpublished draft
POST	`/tools/{tool}/publish`	Freezes the tool draft into a new immutable version that pinned assistants can resolve
GET	`/tools/{tool}/validate`	Runs the publish-time checks against the tool draft without publishing and returns the error list
GET	`/tools/{tool}/versions`	Lists the tool's published versions, newest first
GET	`/tools/{tool}/versions/{version}`	Returns one published tool version including its frozen configuration
POST	`/tools/{tool}/versions/{version}/restore`	Copies an old tool version back onto the draft and publishes it as a new, higher-numbered version

Endpoint-uri

Lists the organization's tools, newest first, filterable by type, publication state and MCP server

GET/tools

Necesită tool.read.
Query params: type, published_only, mcp_server_id, limit (default 25, capped at 100).

Parametri de interogare

Nume	Tip	Obligatoriu	Note
`published_only`	boolean	—	default `false`
`limit`	integer	—	default `25`

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/tools?published_only=false&limit=25" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/tools?published_only=false&limit=25`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/tools?published_only=false&limit=25');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/tools?published_only=false&limit=25",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	Paginated set of `ToolResource`

Erori

Status	Când apare
`403`	The key lacks tool.read

Exemplu de răspuns, generat din schemă:

json

{
  "data": [
    {
      "id": "01JQ0000000000000000000000",
      "object": "string",
      "name": "Support Line",
      "key": "string",
      "description": "string",
      "type": "string",
      "status": "string",
      "is_published": true,
      "version": 1,
      "current_version_id": "01JQ0000000000000000000000",
      "parameters_schema": {},
      "config": {},
      "messages": {},
      "rejection_plan": {},
      "server": {},
      "is_async": true,
      "timeout_seconds": 30,
      "requires_confirmation": true,
      "risk_level": "string",
      "mcp_server_id": "01JQ0000000000000000000000",
      "mcp_tool_name": "Support Line",
      "metadata": {},
      "created_at": "2026-01-01T12:00:00+00:00",
      "updated_at": "2026-01-01T12:00:00+00:00"
    }
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {}
    ],
    "path": "string",
    "per_page": 25,
    "to": 1,
    "total": 1
  }
}

Creates a draft tool, validating the outbound HTTP request configuration for request-making types

POST/tools

Necesită tool.write.
name, description and type are all required. For HTTP tool types the same validator that gates publishing runs at create time.

Corpul cererii

Câmp	Tip	Obligatoriu	Note
`name`	string	da	max 255 chars
`key`	string \| null	—	max 96 chars. pattern `^[a-zA-Z_][a-zA-Z0-9_]*$`
`description`	string	da	max 2000 chars
`type`	`api_request` · `function` · `transfer_call` · `handoff` · `end_call` · `sms` …	da	§32. The type drives everything downstream: which form fields the builder shows, which validator runs, and whether the Voice Gateway executes the tool in-process, over HTTP, or in an isolated sandbox worker.
`parameters_schema`	string[] \| null	—
`config`	string[] \| null	—
`messages`	string[] \| null	—
`rejection_plan`	string[] \| null	—
`server`	string[] \| null	—
`is_async`	boolean \| null	—
`timeout_seconds`	integer \| null	—	min 1. max 120
`requires_confirmation`	boolean \| null	—
`risk_level`	`read` · `write` · `destructive` · `financial` · `privileged` \| null	—
`metadata`	string[] \| null	—

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/tools" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "name": "Support Line",
       "description": "string",
       "type": "api_request",
       "is_async": true,
       "timeout_seconds": 30,
       "requires_confirmation": true,
       "risk_level": "read"
     }'

const response = await fetch(`${process.env.CALLAGENT_API_URL}/tools`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Support Line",
    "description": "string",
    "type": "api_request",
    "is_async": true,
    "timeout_seconds": 30,
    "requires_confirmation": true,
    "risk_level": "read"
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/tools');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Support Line',
    'description' => 'string',
    'type' => 'api_request',
    'is_async' => true,
    'timeout_seconds' => 30,
    'requires_confirmation' => true,
    'risk_level' => 'read',
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/tools",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "name": "Support Line",
      "description": "string",
      "type": "api_request",
      "is_async": True,
      "timeout_seconds": 30,
      "requires_confirmation": True,
      "risk_level": "read"
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`201`	`ToolResource`

Erori

Status	Când apare
`403`	The key lacks tool.write
`422`	Validation failed, including structural errors reported on `config`

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "object": "string",
    "name": "Support Line",
    "key": "string",
    "description": "string",
    "type": "string",
    "status": "string",
    "is_published": true,
    "version": 1,
    "current_version_id": "01JQ0000000000000000000000",
    "parameters_schema": {},
    "config": {},
    "messages": {},
    "rejection_plan": {},
    "server": {},
    "is_async": true,
    "timeout_seconds": 30,
    "requires_confirmation": true,
    "risk_level": "string",
    "mcp_server_id": "01JQ0000000000000000000000",
    "mcp_tool_name": "Support Line",
    "metadata": {},
    "created_at": "2026-01-01T12:00:00+00:00",
    "updated_at": "2026-01-01T12:00:00+00:00"
  }
}

Returns one tool with its parameter schema and provider configuration

GET/tools/{tool}

Necesită tool.read.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`tool`	string	da	The tool ID

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/tools/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/tools/01JQ0000000000000000000000`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/tools/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/tools/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`ToolResource`

Erori

Status	Când apare
`403`	The key lacks tool.read
`404`	No such tool in this organization

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "object": "string",
    "name": "Support Line",
    "key": "string",
    "description": "string",
    "type": "string",
    "status": "string",
    "is_published": true,
    "version": 1,
    "current_version_id": "01JQ0000000000000000000000",
    "parameters_schema": {},
    "config": {},
    "messages": {},
    "rejection_plan": {},
    "server": {},
    "is_async": true,
    "timeout_seconds": 30,
    "requires_confirmation": true,
    "risk_level": "string",
    "mcp_server_id": "01JQ0000000000000000000000",
    "mcp_tool_name": "Support Line",
    "metadata": {},
    "created_at": "2026-01-01T12:00:00+00:00",
    "updated_at": "2026-01-01T12:00:00+00:00"
  }
}

Updates a tool draft with PATCH semantics, re-running the HTTP config validator when relevant

PUT/tools/{tool}

Necesită tool.write.
PATCH este acceptat pe aceeași cale, cu același corp.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`tool`	string	da	The tool ID

Corpul cererii

Câmp	Tip	Obligatoriu	Note
`name`	string	—	max 255 chars
`key`	string \| null	—	max 96 chars. pattern `^[a-zA-Z_][a-zA-Z0-9_]*$`
`description`	string	—	max 2000 chars
`type`	`api_request` · `function` · `transfer_call` · `handoff` · `end_call` · `sms` …	—	§32. The type drives everything downstream: which form fields the builder shows, which validator runs, and whether the Voice Gateway executes the tool in-process, over HTTP, or in an isolated sandbox worker.
`parameters_schema`	string[] \| null	—
`config`	string[] \| null	—
`messages`	string[] \| null	—
`rejection_plan`	string[] \| null	—
`server`	string[] \| null	—
`is_async`	boolean \| null	—
`timeout_seconds`	integer \| null	—	min 1. max 120
`requires_confirmation`	boolean \| null	—
`risk_level`	`read` · `write` · `destructive` · `financial` · `privileged` \| null	—
`metadata`	string[] \| null	—

cURLJavaScriptPHPPython

bash

curl -X PUT "$CALLAGENT_API_URL/tools/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "name": "Support Line",
       "type": "api_request",
       "is_async": true,
       "timeout_seconds": 30,
       "requires_confirmation": true,
       "risk_level": "read"
     }'

const response = await fetch(`${process.env.CALLAGENT_API_URL}/tools/01JQ0000000000000000000000`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Support Line",
    "type": "api_request",
    "is_async": true,
    "timeout_seconds": 30,
    "requires_confirmation": true,
    "risk_level": "read"
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/tools/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Support Line',
    'type' => 'api_request',
    'is_async' => true,
    'timeout_seconds' => 30,
    'requires_confirmation' => true,
    'risk_level' => 'read',
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.put(
    f"{os.environ['CALLAGENT_API_URL']}/tools/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "name": "Support Line",
      "type": "api_request",
      "is_async": True,
      "timeout_seconds": 30,
      "requires_confirmation": True,
      "risk_level": "read"
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`ToolResource`

Erori

Status	Când apare
`403`	The key lacks tool.write
`404`	No such tool in this organization
`422`	Validation failed, including structural errors on `config`

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "object": "string",
    "name": "Support Line",
    "key": "string",
    "description": "string",
    "type": "string",
    "status": "string",
    "is_published": true,
    "version": 1,
    "current_version_id": "01JQ0000000000000000000000",
    "parameters_schema": {},
    "config": {},
    "messages": {},
    "rejection_plan": {},
    "server": {},
    "is_async": true,
    "timeout_seconds": 30,
    "requires_confirmation": true,
    "risk_level": "string",
    "mcp_server_id": "01JQ0000000000000000000000",
    "mcp_tool_name": "Support Line",
    "metadata": {},
    "created_at": "2026-01-01T12:00:00+00:00",
    "updated_at": "2026-01-01T12:00:00+00:00"
  }
}

Deletes a tool from the organization

DELETE/tools/{tool}

Necesită tool.delete.
Acest răspuns nu este împachetat în data.
Body is a bare {"deleted": true, "id": "..."}. Deleting needs tool.delete, which is a distinct permission from tool.write.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`tool`	string	da	The tool ID

cURLJavaScriptPHPPython

bash

curl -X DELETE "$CALLAGENT_API_URL/tools/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/tools/01JQ0000000000000000000000`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/tools/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.delete(
    f"{os.environ['CALLAGENT_API_URL']}/tools/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	Bare JSON object, not `data`-wrapped

Erori

Status	Când apare
`403`	The key lacks tool.delete
`404`	No such tool in this organization

Exemplu de răspuns, generat din schemă:

json

{
  "deleted": true,
  "id": null
}

Copies a tool into a new unpublished draft

POST/tools/{tool}/duplicate

Necesită tool.write + tool.read.
Requires both tool.write (create) and tool.read (view the source). Optional body field name.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`tool`	string	da	The tool ID

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/tools/01JQ0000000000000000000000/duplicate" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/tools/01JQ0000000000000000000000/duplicate`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/tools/01JQ0000000000000000000000/duplicate');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/tools/01JQ0000000000000000000000/duplicate",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`201`	`ToolResource`

Erori

Status	Când apare
`403`	The key lacks tool.write or tool.read
`404`	No such tool in this organization

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "object": "string",
    "name": "Support Line",
    "key": "string",
    "description": "string",
    "type": "string",
    "status": "string",
    "is_published": true,
    "version": 1,
    "current_version_id": "01JQ0000000000000000000000",
    "parameters_schema": {},
    "config": {},
    "messages": {},
    "rejection_plan": {},
    "server": {},
    "is_async": true,
    "timeout_seconds": 30,
    "requires_confirmation": true,
    "risk_level": "string",
    "mcp_server_id": "01JQ0000000000000000000000",
    "mcp_tool_name": "Support Line",
    "metadata": {},
    "created_at": "2026-01-01T12:00:00+00:00",
    "updated_at": "2026-01-01T12:00:00+00:00"
  }
}

Freezes the tool draft into a new immutable version that pinned assistants can resolve

POST/tools/{tool}/publish

Necesită tool.write.
Publishing a tool never touches an existing assistant version; a pinned assistant keeps resolving its old version. Optional body field change_summary.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`tool`	string	da	The tool ID

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/tools/01JQ0000000000000000000000/publish" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/tools/01JQ0000000000000000000000/publish`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/tools/01JQ0000000000000000000000/publish');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/tools/01JQ0000000000000000000000/publish",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`201`	`ToolVersionResource`

Erori

Status	Când apare
`403`	The key lacks tool.write
`404`	No such tool in this organization
`422`	The tool fails publish-time validation

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "object": "string",
    "tool_id": "01JQ0000000000000000000000",
    "version": 1,
    "name": "Support Line",
    "key": "string",
    "type": "string",
    "description": "string",
    "parameters_schema": {},
    "config": {},
    "config_hash": "string",
    "change_summary": "string",
    "published_at": "2026-01-01T12:00:00+00:00"
  }
}

Runs the publish-time checks against the tool draft without publishing and returns the error list

GET/tools/{tool}/validate

Necesită tool.read.
A failing tool still answers 200 with valid:false — it is a report, not an error.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`tool`	string	da	The tool ID

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/tools/01JQ0000000000000000000000/validate" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/tools/01JQ0000000000000000000000/validate`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/tools/01JQ0000000000000000000000/validate');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/tools/01JQ0000000000000000000000/validate",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`data`-wrapped object

Erori

Status	Când apare
`403`	The key lacks tool.read
`404`	No such tool in this organization

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "valid": true,
    "errors": [
      null
    ]
  }
}

Lists the tool's published versions, newest first

GET/tools/{tool}/versions

Necesită tool.read.
Page size is fixed at 50 and cannot be changed.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`tool`	string	da	The tool ID

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/tools/01JQ0000000000000000000000/versions" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/tools/01JQ0000000000000000000000/versions`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/tools/01JQ0000000000000000000000/versions');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/tools/01JQ0000000000000000000000/versions",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	Paginated set of `ToolVersionResource`

Erori

Status	Când apare
`403`	The key lacks tool.read
`404`	No such tool in this organization

Exemplu de răspuns, generat din schemă:

json

{
  "data": [
    {
      "id": "01JQ0000000000000000000000",
      "object": "string",
      "tool_id": "01JQ0000000000000000000000",
      "version": 1,
      "name": "Support Line",
      "key": "string",
      "type": "string",
      "description": "string",
      "parameters_schema": {},
      "config": {},
      "config_hash": "string",
      "change_summary": "string",
      "published_at": "2026-01-01T12:00:00+00:00"
    }
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {}
    ],
    "path": "string",
    "per_page": 25,
    "to": 1,
    "total": 1
  }
}

Returns one published tool version including its frozen configuration

GET/tools/{tool}/versions/{version}

Necesită tool.read.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`tool`	string	da	The tool ID
`version`	string	da	The version ID

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/tools/01JQ0000000000000000000000/versions/3" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/tools/01JQ0000000000000000000000/versions/3`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/tools/01JQ0000000000000000000000/versions/3');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/tools/01JQ0000000000000000000000/versions/3",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`200`	`ToolVersionResource`

Erori

Status	Când apare
`403`	The key lacks tool.read
`404`	No such tool, or the version belongs to another tool

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "object": "string",
    "tool_id": "01JQ0000000000000000000000",
    "version": 1,
    "name": "Support Line",
    "key": "string",
    "type": "string",
    "description": "string",
    "parameters_schema": {},
    "config": {},
    "config_hash": "string",
    "change_summary": "string",
    "published_at": "2026-01-01T12:00:00+00:00"
  }
}

Copies an old tool version back onto the draft and publishes it as a new, higher-numbered version

POST/tools/{tool}/versions/{version}/restore

Necesită tool.write.
Always republishes; there is no dry-run flag. A republish validation failure escapes uncaught as 500, not 422.

Parametri de cale

Nume	Tip	Obligatoriu	Note
`tool`	string	da	The tool ID
`version`	string	da	The version ID

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/tools/01JQ0000000000000000000000/versions/3/restore" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/tools/01JQ0000000000000000000000/versions/3/restore`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/tools/01JQ0000000000000000000000/versions/3/restore');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/tools/01JQ0000000000000000000000/versions/3/restore",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
`201`	`ToolVersionResource`

Erori

Status	Când apare
`403`	The key lacks tool.write
`404`	No such tool, or the version belongs to another tool

Exemplu de răspuns, generat din schemă:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "object": "string",
    "tool_id": "01JQ0000000000000000000000",
    "version": 1,
    "name": "Support Line",
    "key": "string",
    "type": "string",
    "description": "string",
    "parameters_schema": {},
    "config": {},
    "config_hash": "string",
    "change_summary": "string",
    "published_at": "2026-01-01T12:00:00+00:00"
  }
}

Tools ​

Endpoint-uri ​

Lists the organization's tools, newest first, filterable by type, publication state and MCP server ​

Creates a draft tool, validating the outbound HTTP request configuration for request-making types ​

Returns one tool with its parameter schema and provider configuration ​

Updates a tool draft with PATCH semantics, re-running the HTTP config validator when relevant ​

Deletes a tool from the organization ​

Copies a tool into a new unpublished draft ​

Freezes the tool draft into a new immutable version that pinned assistants can resolve ​

Runs the publish-time checks against the tool draft without publishing and returns the error list ​

Lists the tool's published versions, newest first ​

Returns one published tool version including its frozen configuration ​

Copies an old tool version back onto the draft and publishes it as a new, higher-numbered version ​

Tools

Endpoint-uri

Lists the organization's tools, newest first, filterable by type, publication state and MCP server

Creates a draft tool, validating the outbound HTTP request configuration for request-making types

Returns one tool with its parameter schema and provider configuration

Updates a tool draft with PATCH semantics, re-running the HTTP config validator when relevant

Deletes a tool from the organization

Copies a tool into a new unpublished draft

Freezes the tool draft into a new immutable version that pinned assistants can resolve

Runs the publish-time checks against the tool draft without publishing and returns the error list

Lists the tool's published versions, newest first

Returns one published tool version including its frozen configuration

Copies an old tool version back onto the draft and publishes it as a new, higher-numbered version