Update Tool - Cartesia Docs

Update a tool

curl --request PATCH \
  --url https://api.cartesia.ai/v1/agents/tools/{tool_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Cartesia-Version: <cartesia-version>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "api_schema": {
    "authentication": {
      "mode": "basic_auth",
      "password": {
        "type": "secret",
        "secret_description": "<string>",
        "secret_value": "<string>"
      },
      "username": "<string>"
    },
    "path_params_schema": {},
    "query_params_schema": {
      "properties": {},
      "required": [
        "<string>"
      ]
    },
    "request_body_schema": {
      "constant_value": "<string>",
      "description": "<string>",
      "enum": [
        "<string>"
      ],
      "items": "<unknown>",
      "properties": {},
      "required": [
        "<string>"
      ]
    },
    "request_headers": {},
    "url": "<string>"
  },
  "description": "<string>",
  "name": "<string>",
  "response_timeout_secs": 60
}
'

import requests

url = "https://api.cartesia.ai/v1/agents/tools/{tool_id}"

payload = {
    "api_schema": {
        "authentication": {
            "mode": "basic_auth",
            "password": {
                "type": "secret",
                "secret_description": "<string>",
                "secret_value": "<string>"
            },
            "username": "<string>"
        },
        "path_params_schema": {},
        "query_params_schema": {
            "properties": {},
            "required": ["<string>"]
        },
        "request_body_schema": {
            "constant_value": "<string>",
            "description": "<string>",
            "enum": ["<string>"],
            "items": "<unknown>",
            "properties": {},
            "required": ["<string>"]
        },
        "request_headers": {},
        "url": "<string>"
    },
    "description": "<string>",
    "name": "<string>",
    "response_timeout_secs": 60
}
headers = {
    "Cartesia-Version": "<cartesia-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {
    'Cartesia-Version': '<cartesia-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    api_schema: {
      authentication: {
        mode: 'basic_auth',
        password: {type: 'secret', secret_description: '<string>', secret_value: '<string>'},
        username: '<string>'
      },
      path_params_schema: {},
      query_params_schema: {properties: {}, required: ['<string>']},
      request_body_schema: {
        constant_value: '<string>',
        description: '<string>',
        enum: ['<string>'],
        items: '<unknown>',
        properties: {},
        required: ['<string>']
      },
      request_headers: {},
      url: '<string>'
    },
    description: '<string>',
    name: '<string>',
    response_timeout_secs: 60
  })
};

fetch('https://api.cartesia.ai/v1/agents/tools/{tool_id}', 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.cartesia.ai/v1/agents/tools/{tool_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'api_schema' => [
        'authentication' => [
                'mode' => 'basic_auth',
                'password' => [
                                'type' => 'secret',
                                'secret_description' => '<string>',
                                'secret_value' => '<string>'
                ],
                'username' => '<string>'
        ],
        'path_params_schema' => [
                
        ],
        'query_params_schema' => [
                'properties' => [
                                
                ],
                'required' => [
                                '<string>'
                ]
        ],
        'request_body_schema' => [
                'constant_value' => '<string>',
                'description' => '<string>',
                'enum' => [
                                '<string>'
                ],
                'items' => '<unknown>',
                'properties' => [
                                
                ],
                'required' => [
                                '<string>'
                ]
        ],
        'request_headers' => [
                
        ],
        'url' => '<string>'
    ],
    'description' => '<string>',
    'name' => '<string>',
    'response_timeout_secs' => 60
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Cartesia-Version: <cartesia-version>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cartesia.ai/v1/agents/tools/{tool_id}"

	payload := strings.NewReader("{\n  \"api_schema\": {\n    \"authentication\": {\n      \"mode\": \"basic_auth\",\n      \"password\": {\n        \"type\": \"secret\",\n        \"secret_description\": \"<string>\",\n        \"secret_value\": \"<string>\"\n      },\n      \"username\": \"<string>\"\n    },\n    \"path_params_schema\": {},\n    \"query_params_schema\": {\n      \"properties\": {},\n      \"required\": [\n        \"<string>\"\n      ]\n    },\n    \"request_body_schema\": {\n      \"constant_value\": \"<string>\",\n      \"description\": \"<string>\",\n      \"enum\": [\n        \"<string>\"\n      ],\n      \"items\": \"<unknown>\",\n      \"properties\": {},\n      \"required\": [\n        \"<string>\"\n      ]\n    },\n    \"request_headers\": {},\n    \"url\": \"<string>\"\n  },\n  \"description\": \"<string>\",\n  \"name\": \"<string>\",\n  \"response_timeout_secs\": 60\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Cartesia-Version", "<cartesia-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.cartesia.ai/v1/agents/tools/{tool_id}")
  .header("Cartesia-Version", "<cartesia-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"api_schema\": {\n    \"authentication\": {\n      \"mode\": \"basic_auth\",\n      \"password\": {\n        \"type\": \"secret\",\n        \"secret_description\": \"<string>\",\n        \"secret_value\": \"<string>\"\n      },\n      \"username\": \"<string>\"\n    },\n    \"path_params_schema\": {},\n    \"query_params_schema\": {\n      \"properties\": {},\n      \"required\": [\n        \"<string>\"\n      ]\n    },\n    \"request_body_schema\": {\n      \"constant_value\": \"<string>\",\n      \"description\": \"<string>\",\n      \"enum\": [\n        \"<string>\"\n      ],\n      \"items\": \"<unknown>\",\n      \"properties\": {},\n      \"required\": [\n        \"<string>\"\n      ]\n    },\n    \"request_headers\": {},\n    \"url\": \"<string>\"\n  },\n  \"description\": \"<string>\",\n  \"name\": \"<string>\",\n  \"response_timeout_secs\": 60\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cartesia.ai/v1/agents/tools/{tool_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Cartesia-Version"] = '<cartesia-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"api_schema\": {\n    \"authentication\": {\n      \"mode\": \"basic_auth\",\n      \"password\": {\n        \"type\": \"secret\",\n        \"secret_description\": \"<string>\",\n        \"secret_value\": \"<string>\"\n      },\n      \"username\": \"<string>\"\n    },\n    \"path_params_schema\": {},\n    \"query_params_schema\": {\n      \"properties\": {},\n      \"required\": [\n        \"<string>\"\n      ]\n    },\n    \"request_body_schema\": {\n      \"constant_value\": \"<string>\",\n      \"description\": \"<string>\",\n      \"enum\": [\n        \"<string>\"\n      ],\n      \"items\": \"<unknown>\",\n      \"properties\": {},\n      \"required\": [\n        \"<string>\"\n      ]\n    },\n    \"request_headers\": {},\n    \"url\": \"<string>\"\n  },\n  \"description\": \"<string>\",\n  \"name\": \"<string>\",\n  \"response_timeout_secs\": 60\n}"

response = http.request(request)
puts response.read_body

{
  "api_schema": {
    "method": "GET",
    "url": "<string>",
    "authentication": {
      "mode": "basic_auth",
      "password": {
        "type": "secret",
        "secret_description": "<string>"
      },
      "username": "<string>"
    },
    "path_params_schema": {},
    "query_params_schema": {
      "properties": {},
      "required": [
        "<string>"
      ]
    },
    "request_body_schema": {
      "type": "string",
      "constant_value": "<string>",
      "description": "<string>",
      "enum": [
        "<string>"
      ],
      "items": "<unknown>",
      "properties": {},
      "required": [
        "<string>"
      ]
    },
    "request_headers": {}
  },
  "created_at": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "execution_mode": "immediate",
  "id": "<string>",
  "name": "<string>",
  "pre_tool_speech": "auto",
  "response_timeout_secs": 20,
  "type": "webhook",
  "updated_at": "2023-11-07T05:31:56Z",
  "agents": [
    {
      "created_at": "2023-11-07T05:31:56Z",
      "description": "<string>",
      "id": "<string>",
      "name": "<string>",
      "updated_at": "2023-11-07T05:31:56Z",
      "version_id": "<string>"
    }
  ]
}

{
  "message": "<string>",
  "request_id": "<string>",
  "title": "<string>",
  "doc_url": "<string>",
  "error_code": "<string>"
}

PATCH

agents

tools

{tool_id}

Update a tool

curl --request PATCH \
  --url https://api.cartesia.ai/v1/agents/tools/{tool_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Cartesia-Version: <cartesia-version>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "api_schema": {
    "authentication": {
      "mode": "basic_auth",
      "password": {
        "type": "secret",
        "secret_description": "<string>",
        "secret_value": "<string>"
      },
      "username": "<string>"
    },
    "path_params_schema": {},
    "query_params_schema": {
      "properties": {},
      "required": [
        "<string>"
      ]
    },
    "request_body_schema": {
      "constant_value": "<string>",
      "description": "<string>",
      "enum": [
        "<string>"
      ],
      "items": "<unknown>",
      "properties": {},
      "required": [
        "<string>"
      ]
    },
    "request_headers": {},
    "url": "<string>"
  },
  "description": "<string>",
  "name": "<string>",
  "response_timeout_secs": 60
}
'

import requests

url = "https://api.cartesia.ai/v1/agents/tools/{tool_id}"

payload = {
    "api_schema": {
        "authentication": {
            "mode": "basic_auth",
            "password": {
                "type": "secret",
                "secret_description": "<string>",
                "secret_value": "<string>"
            },
            "username": "<string>"
        },
        "path_params_schema": {},
        "query_params_schema": {
            "properties": {},
            "required": ["<string>"]
        },
        "request_body_schema": {
            "constant_value": "<string>",
            "description": "<string>",
            "enum": ["<string>"],
            "items": "<unknown>",
            "properties": {},
            "required": ["<string>"]
        },
        "request_headers": {},
        "url": "<string>"
    },
    "description": "<string>",
    "name": "<string>",
    "response_timeout_secs": 60
}
headers = {
    "Cartesia-Version": "<cartesia-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {
    'Cartesia-Version': '<cartesia-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    api_schema: {
      authentication: {
        mode: 'basic_auth',
        password: {type: 'secret', secret_description: '<string>', secret_value: '<string>'},
        username: '<string>'
      },
      path_params_schema: {},
      query_params_schema: {properties: {}, required: ['<string>']},
      request_body_schema: {
        constant_value: '<string>',
        description: '<string>',
        enum: ['<string>'],
        items: '<unknown>',
        properties: {},
        required: ['<string>']
      },
      request_headers: {},
      url: '<string>'
    },
    description: '<string>',
    name: '<string>',
    response_timeout_secs: 60
  })
};

fetch('https://api.cartesia.ai/v1/agents/tools/{tool_id}', 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.cartesia.ai/v1/agents/tools/{tool_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'api_schema' => [
        'authentication' => [
                'mode' => 'basic_auth',
                'password' => [
                                'type' => 'secret',
                                'secret_description' => '<string>',
                                'secret_value' => '<string>'
                ],
                'username' => '<string>'
        ],
        'path_params_schema' => [
                
        ],
        'query_params_schema' => [
                'properties' => [
                                
                ],
                'required' => [
                                '<string>'
                ]
        ],
        'request_body_schema' => [
                'constant_value' => '<string>',
                'description' => '<string>',
                'enum' => [
                                '<string>'
                ],
                'items' => '<unknown>',
                'properties' => [
                                
                ],
                'required' => [
                                '<string>'
                ]
        ],
        'request_headers' => [
                
        ],
        'url' => '<string>'
    ],
    'description' => '<string>',
    'name' => '<string>',
    'response_timeout_secs' => 60
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Cartesia-Version: <cartesia-version>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cartesia.ai/v1/agents/tools/{tool_id}"

	payload := strings.NewReader("{\n  \"api_schema\": {\n    \"authentication\": {\n      \"mode\": \"basic_auth\",\n      \"password\": {\n        \"type\": \"secret\",\n        \"secret_description\": \"<string>\",\n        \"secret_value\": \"<string>\"\n      },\n      \"username\": \"<string>\"\n    },\n    \"path_params_schema\": {},\n    \"query_params_schema\": {\n      \"properties\": {},\n      \"required\": [\n        \"<string>\"\n      ]\n    },\n    \"request_body_schema\": {\n      \"constant_value\": \"<string>\",\n      \"description\": \"<string>\",\n      \"enum\": [\n        \"<string>\"\n      ],\n      \"items\": \"<unknown>\",\n      \"properties\": {},\n      \"required\": [\n        \"<string>\"\n      ]\n    },\n    \"request_headers\": {},\n    \"url\": \"<string>\"\n  },\n  \"description\": \"<string>\",\n  \"name\": \"<string>\",\n  \"response_timeout_secs\": 60\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Cartesia-Version", "<cartesia-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.cartesia.ai/v1/agents/tools/{tool_id}")
  .header("Cartesia-Version", "<cartesia-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"api_schema\": {\n    \"authentication\": {\n      \"mode\": \"basic_auth\",\n      \"password\": {\n        \"type\": \"secret\",\n        \"secret_description\": \"<string>\",\n        \"secret_value\": \"<string>\"\n      },\n      \"username\": \"<string>\"\n    },\n    \"path_params_schema\": {},\n    \"query_params_schema\": {\n      \"properties\": {},\n      \"required\": [\n        \"<string>\"\n      ]\n    },\n    \"request_body_schema\": {\n      \"constant_value\": \"<string>\",\n      \"description\": \"<string>\",\n      \"enum\": [\n        \"<string>\"\n      ],\n      \"items\": \"<unknown>\",\n      \"properties\": {},\n      \"required\": [\n        \"<string>\"\n      ]\n    },\n    \"request_headers\": {},\n    \"url\": \"<string>\"\n  },\n  \"description\": \"<string>\",\n  \"name\": \"<string>\",\n  \"response_timeout_secs\": 60\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cartesia.ai/v1/agents/tools/{tool_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Cartesia-Version"] = '<cartesia-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"api_schema\": {\n    \"authentication\": {\n      \"mode\": \"basic_auth\",\n      \"password\": {\n        \"type\": \"secret\",\n        \"secret_description\": \"<string>\",\n        \"secret_value\": \"<string>\"\n      },\n      \"username\": \"<string>\"\n    },\n    \"path_params_schema\": {},\n    \"query_params_schema\": {\n      \"properties\": {},\n      \"required\": [\n        \"<string>\"\n      ]\n    },\n    \"request_body_schema\": {\n      \"constant_value\": \"<string>\",\n      \"description\": \"<string>\",\n      \"enum\": [\n        \"<string>\"\n      ],\n      \"items\": \"<unknown>\",\n      \"properties\": {},\n      \"required\": [\n        \"<string>\"\n      ]\n    },\n    \"request_headers\": {},\n    \"url\": \"<string>\"\n  },\n  \"description\": \"<string>\",\n  \"name\": \"<string>\",\n  \"response_timeout_secs\": 60\n}"

response = http.request(request)
puts response.read_body

{
  "api_schema": {
    "method": "GET",
    "url": "<string>",
    "authentication": {
      "mode": "basic_auth",
      "password": {
        "type": "secret",
        "secret_description": "<string>"
      },
      "username": "<string>"
    },
    "path_params_schema": {},
    "query_params_schema": {
      "properties": {},
      "required": [
        "<string>"
      ]
    },
    "request_body_schema": {
      "type": "string",
      "constant_value": "<string>",
      "description": "<string>",
      "enum": [
        "<string>"
      ],
      "items": "<unknown>",
      "properties": {},
      "required": [
        "<string>"
      ]
    },
    "request_headers": {}
  },
  "created_at": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "execution_mode": "immediate",
  "id": "<string>",
  "name": "<string>",
  "pre_tool_speech": "auto",
  "response_timeout_secs": 20,
  "type": "webhook",
  "updated_at": "2023-11-07T05:31:56Z",
  "agents": [
    {
      "created_at": "2023-11-07T05:31:56Z",
      "description": "<string>",
      "id": "<string>",
      "name": "<string>",
      "updated_at": "2023-11-07T05:31:56Z",
      "version_id": "<string>"
    }
  ]
}

{
  "message": "<string>",
  "request_id": "<string>",
  "title": "<string>",
  "doc_url": "<string>",
  "error_code": "<string>"
}

Authorizations

Authorization

string

header

default:$CARTESIA_API_KEY

required

Cartesia API key (sk_car_...). Get one at play.cartesia.ai/keys.

Headers

Cartesia-Version

enum<string>

default:2026-08-14

required

API version header.

Available options:

2026-08-14

Example:

"2026-08-14"

Path Parameters

tool_id

string

required

Unique identifier for the tool.

Minimum string length: 1

Body

application/json

Webhook tool update
Client tool update

api_schema

object

Show child attributes

description

string

What the tool does and when the agent should use it.

Required string length: 1 - 2000

execution_mode

enum<string>

Controls how the tool runs relative to the conversation. immediate runs in the current turn and can be interrupted by the caller. async lets the turn finish while the tool runs.

Available options:

immediate,

async

name

string

Name the agent uses to call the tool. Names are case-sensitive.

Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$

pre_tool_speech

enum<string>

Controls whether the agent speaks before using the tool. auto lets the agent decide, while force asks the agent to speak first.

Available options:

auto,

force

response_timeout_secs

integer

Maximum time to wait for the endpoint to respond. Defaults to 20 seconds.

Required range: 1 <= x <= 120

Response

Update a tool

Webhook tool
Client tool

api_schema

ManagedWebhookApiSchemaResponse · object

required

Show child attributes

created_at

string<date-time>

required

An RFC 3339 / ISO 8601 date-time string with timezone (e.g. 2025-04-16T12:34:56.789Z).

description

string

required

What the tool does and when the agent should use it.

Required string length: 1 - 2000

execution_mode

enum<string>

required

Controls how the tool runs relative to the conversation. immediate runs in the current turn and can be interrupted by the caller, while async lets the turn finish while the tool runs.

Available options:

immediate,

async

string

required

Unique identifier for the tool.

Minimum string length: 1

name

string

required

Name the agent uses to call the tool. Names are case-sensitive.

Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$

pre_tool_speech

enum<string>

required

Controls whether the agent speaks before using the tool. auto lets the agent decide, while force asks the agent to speak first.

Available options:

auto,

force

response_timeout_secs

integer

default:20

required

Maximum time to wait for the endpoint to respond. Defaults to 20 seconds.

Required range: 1 <= x <= 120

type

enum<string>

required

Runs an HTTP request from Cartesia's servers.

Available options:

webhook

updated_at

string<date-time>

required

An RFC 3339 / ISO 8601 date-time string with timezone (e.g. 2025-04-16T12:34:56.789Z).

agents

ManagedAgentSummary · object[]

Agents that currently use this tool. Included when expand[]=agents is requested.

Show child attributes