> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravan.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Agent Tool
> Create Agent Tool.
### Authorizations
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
The internal name of the resource. Use a clear name that your team can recognize in the dashboard and API responses.
A short description of the resource. Use it to explain the purpose, behavior, or usage context.
The tool type. Use the value that matches how the agent should execute the tool, such as an API or integration tool.
The tool definition object. Include the schema, parameters, and execution details required by the tool type.
***
### Response
Whether the request succeeded.
Human-readable status message.
Returned data.
Unique tool ID
Tool name
Tool description
Tool type (e.g. webhook, function)
Tool definition schema
Organization this tool belongs to
Whether the tool is active
```json 200 theme={null}
{
"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:
```json theme={null}
{"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:
```json 200 theme={null}
{
"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:
```json theme={null}
{"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):
```json 200 theme={null}
{
"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:
```json theme={null}
{"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:
```json 200 theme={null}
{
"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:
```json theme={null}
{"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):
```json 200 theme={null}
{
"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": []
}
}
}
```
## OpenAPI
````yaml POST /api/v1/tools/
openapi: 3.0.1
info:
title: Agni API
version: 1.0.0
description: >-
Agni API for managing agents, tools, widget settings, telephony, and
integrations.
servers:
- url: https://api.ravan.ai
security:
- X-Api-Key: []
tags:
- name: AgentService
- name: AgentToolService
- name: WidgetSettingsService
- name: PhoneService
- name: AppointmentService
- name: GHLService
- name: CalComService
- name: CampaignService
- name: ContactService
- name: CallingService
- name: RAGService
- name: ModelService
- name: HealthService
paths:
/api/v1/tools/:
post:
tags:
- AgentToolService
summary: Create Agent Tool
operationId: CreateAgentTool
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAgentToolRequest'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAgentToolResponse'
components:
schemas:
CreateAgentToolRequest:
type: object
properties:
name:
type: string
description: Tool name
description:
type: string
description: Tool description
type:
type: string
description: Tool type (e.g. webhook, function)
definition:
type: object
description: Tool definition schema
CreateAgentToolResponse:
type: object
properties:
success:
type: boolean
message:
type: string
data:
$ref: '#/components/schemas/AgentTool'
AgentTool:
type: object
properties:
id:
type: string
description: Tool UUID
organizationId:
type: string
description: Organization UUID
name:
type: string
description: Tool name
description:
type: string
description: Tool description
type:
type: string
description: Tool type
definition:
$ref: '#/components/schemas/AgentToolDefinition'
isActive:
type: boolean
description: Whether the tool is active
agentId:
type: string
description: Agent UUID attached to the tool
enabledFunctions:
$ref: '#/components/schemas/AgentToolEnabledFunctions'
AgentToolDefinition:
type: object
description: Tool definition payload.
properties:
url:
type: string
example: https://example.com/book
method:
type: string
example: POST
parameters:
type: object
properties:
type:
type: string
example: object
properties:
type: object
additionalProperties:
type: object
properties:
type:
type: string
example: string
additionalProperties: true
AgentToolEnabledFunctions:
type: object
properties:
values:
type: array
items:
type: string
securitySchemes:
X-Api-Key:
type: apiKey
in: header
name: X-Api-Key
````