Skip to main content
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": {}
}
'
{
  "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

​
X-Api-Key
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

​
name
string
The internal name of the resource. Use a clear name that your team can recognize in the dashboard and API responses.
​
description
string
A short description of the resource. Use it to explain the purpose, behavior, or usage context.
​
type
string
The tool type. Use the value that matches how the agent should execute the tool, such as an API or integration tool.
​
definition
object
The tool definition object. Include the schema, parameters, and execution details required by the tool type.

​
Response

​
success
boolean
Whether the request succeeded.
​
message
string
Human-readable status message.
​
data
object
Returned data.
{
  "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"}
Example response:
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"}
Response (demo IDs):
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"}
Response:
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"}
Response (demo values):
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

​
X-Api-Key
string
header
required

Body

application/json
​
name
string

Tool name

​
description
string

Tool description

​
type
string

Tool type (e.g. webhook, function)

​
definition
object

Tool definition schema

Response

200 - application/json

Successful response

​
success
boolean
​
message
string
​
data
object