Create Agent Tool
curl --request POST \
--url https://api.ravan.ai/api/v1/tools/ \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--data '
{
"name": "<string>",
"description": "<string>",
"type": "<string>",
"definition": {}
}
'import requests
url = "https://api.ravan.ai/api/v1/tools/"
payload = {
"name": "<string>",
"description": "<string>",
"type": "<string>",
"definition": {}
}
headers = {
"X-Api-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({name: '<string>', description: '<string>', type: '<string>', definition: {}})
};
fetch('https://api.ravan.ai/api/v1/tools/', 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.ravan.ai/api/v1/tools/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'description' => '<string>',
'type' => '<string>',
'definition' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.ravan.ai/api/v1/tools/"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"type\": \"<string>\",\n \"definition\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Api-Key", "<api-key>")
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.post("https://api.ravan.ai/api/v1/tools/")
.header("X-Api-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"type\": \"<string>\",\n \"definition\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.ravan.ai/api/v1/tools/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"type\": \"<string>\",\n \"definition\": {}\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "Request completed successfully",
"data": {
"id": "id_123",
"organizationId": "organization_123",
"name": "Support Bot",
"description": "Example description",
"type": "twilio",
"definition": {},
"isActive": true
}
}
Agent Tool API
Create Agent Tool
Create Agent Tool.
POST
/
api
/
v1
/
tools
/
Create Agent Tool
curl --request POST \
--url https://api.ravan.ai/api/v1/tools/ \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--data '
{
"name": "<string>",
"description": "<string>",
"type": "<string>",
"definition": {}
}
'import requests
url = "https://api.ravan.ai/api/v1/tools/"
payload = {
"name": "<string>",
"description": "<string>",
"type": "<string>",
"definition": {}
}
headers = {
"X-Api-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({name: '<string>', description: '<string>', type: '<string>', definition: {}})
};
fetch('https://api.ravan.ai/api/v1/tools/', 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.ravan.ai/api/v1/tools/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'description' => '<string>',
'type' => '<string>',
'definition' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.ravan.ai/api/v1/tools/"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"type\": \"<string>\",\n \"definition\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Api-Key", "<api-key>")
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.post("https://api.ravan.ai/api/v1/tools/")
.header("X-Api-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"type\": \"<string>\",\n \"definition\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.ravan.ai/api/v1/tools/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"type\": \"<string>\",\n \"definition\": {}\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "Request completed successfully",
"data": {
"id": "id_123",
"organizationId": "organization_123",
"name": "Support Bot",
"description": "Example description",
"type": "twilio",
"definition": {},
"isActive": true
}
}
Authorizations
string
required
Your Agni API key used to authenticate the request. Pass it in the
X-Api-Key header. Find or rotate it from your Ravan AI account settings.Body
string
The internal name of the resource. Use a clear name that your team can recognize in the dashboard and API responses.
string
A short description of the resource. Use it to explain the purpose, behavior, or usage context.
string
The tool type. Use the value that matches how the agent should execute the tool, such as an API or integration tool.
object
The tool definition object. Include the schema, parameters, and execution details required by the tool type.
Response
boolean
Whether the request succeeded.
string
Human-readable status message.
object
{
"success": true,
"message": "Request completed successfully",
"data": {
"id": "id_123",
"organizationId": "organization_123",
"name": "Support Bot",
"description": "Example description",
"type": "twilio",
"definition": {},
"isActive": true
}
}
Transfer Call tool (example)
Example request to create a transfer_call tool:{"id":"demo-tool-id-transfer","name":"transfer_call","description":"Transfer the call to a human agent","type":"transfer_call","definition":{"mode":"cold_transfer","on_hold_music":false,"transfer_to_assign_agent":false,"show_user_number":false,"transfer_to_type":"static","phone_number":"+919999999999","client_transfer_id":"demo-client-transfer-id","custom_prompt":false},"agent_id":"demo-agent-id"}
200
{
"success": true,
"message": "Tool created successfully",
"data": {
"id": "demo-tool-id-transfer",
"organizationId": "demo-org-id",
"name": "transfer_call",
"description": "Transfer the call to a human agent",
"type": "transfer_call",
"definition": {
"client_transfer_id": "demo-client-transfer-id",
"custom_prompt": false,
"mode": "cold_transfer",
"on_hold_music": false,
"phone_number": "+919999999999",
"show_user_number": false,
"transfer_to_assign_agent": false,
"transfer_to_type": "static"
},
"isActive": true,
"agentId": "demo-agent-id",
"enabledFunctions": {
"values": []
}
}
}
End Call tool (example)
Request payload:{"id":"demo-tool-id-end","name":"end_call","description":"when user say bye.","type":"end_call","definition":{},"agent_id":"demo-agent-id"}
200
{
"success": true,
"message": "Tool created successfully",
"data": {
"id": "demo-tool-id-end",
"organizationId": "demo-org-id",
"name": "end_call",
"description": "when user say bye.",
"type": "end_call",
"definition": {},
"isActive": true,
"agentId": "demo-agent-id",
"enabledFunctions": {
"values": []
}
}
}
Custom webhook tool (example)
Request payload:{"name":"webhook test","description":"description","type":"custom","definition":{"custom":{"method":"POST","url":"https://www.google.com","timeoutMs":120000,"headers":[],"queryParameters":[],"payloadArgsOnly":true,"parametersSchemaText":"{\n \"type\": \"object\",\n \"properties\": {\n \"customer_name\": {\n \"type\": \"string\",\n \"description\": \"Customer full name\"\n },\n \"order_id\": {\n \"type\": \"string\",\n \"description\": \"Order identifier\"\n }\n },\n \"required\": [\n \"customer_name\"\n ]\n}","storeFieldsAsVariables":[],"speakDuringExecution":false,"speakAfterExecution":true}},"agent_id":"019eb654-a185-77c6-9555-1d33d120881b"}
200
{
"success": true,
"message": "Tool created successfully",
"data": {
"id": "019eb92c-6834-7ff9-8845-21ffc3273258",
"organizationId": "95a4e479-03a7-4f1b-834d-8705756e8e59",
"name": "webhook test",
"description": "description",
"type": "custom",
"definition": {
"custom": {
"headers": [],
"method": "POST",
"parametersSchemaText": "{\n \"type\": \"object\",\n \"properties\": {\n \"customer_name\": {\n \"type\": \"string\",\n \"description\": \"Customer full name\"\n },\n \"order_id\": {\n \"type\": \"string\",\n \"description\": \"Order identifier\"\n }\n },\n \"required\": [\n \"customer_name\"\n ]\n}",
"payloadArgsOnly": true,
"queryParameters": [],
"speakAfterExecution": true,
"speakDuringExecution": false,
"storeFieldsAsVariables": [],
"timeoutMs": 120000,
"url": "https://www.google.com"
}
},
"isActive": true,
"agentId": "019eb654-a185-77c6-9555-1d33d120881b",
"enabledFunctions": {
"values": []
}
}
}
IVR press_digit tool (example)
Request payload:{"id":"demo-tool-id-ivr","name":"press_digit","description":"Press a digit to navigate the IVR menu","type":"press_digit","definition":{"pause_detection_delay_ms":1000},"agent_id":"demo-agent-id"}
200
{
"success": true,
"message": "Tool created successfully",
"data": {
"id": "demo-tool-id-ivr",
"organizationId": "demo-org-id",
"name": "press_digit",
"description": "Press a digit to navigate the IVR menu",
"type": "press_digit",
"definition": {
"pause_detection_delay_ms": 1000
},
"isActive": true,
"agentId": "demo-agent-id",
"enabledFunctions": {
"values": []
}
}
}
Authorizations
Body
application/json
⌘I

