POST
/
api
/
v1
/
tools
curl -X POST https://api.ravan.ai/api/v1/tools/ \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "check_order_status",
    "description": "Look up the current status of a customer order by order ID",
    "type": "function",
    "definition": {
      "name": "check_order_status",
      "description": "Look up the current status of a customer order",
      "parameters": {
        "type": "object",
        "properties": {
          "order_id": {
            "type": "string",
            "description": "The unique order identifier"
          }
        },
        "required": ["order_id"]
      }
    }
  }'

{
  "success": true,
  "message": "Tool created successfully",
  "data": {
    "id": "019d1fdb-3977-7bd5-ab27-8d3b37ddf4fc",
    "organizationId": "1268c1f0-19f3-47db-aefb-c16a7c3ace6e",
    "name": "check_order_status",
    "description": "Look up the current status of a customer order by order ID",
    "type": "function",
    "definition": {
      "name": "check_order_status",
      "description": "Look up the current status of a customer order",
      "parameters": {
        "type": "object",
        "properties": {
          "order_id": {
            "type": "string",
            "description": "The unique order identifier"
          }
        },
        "required": ["order_id"]
      }
    },
    "isActive": false
  }
}

​
Authorizations

​
X-Api-Key
string
required
Your Agni API key. Find it in your support@ravan.ai under Settings → API Keys.

​
Body

​
name
string
required
Tool name. Must be a valid function name — use lowercase letters, numbers, and underscores only (e.g. check_order_status). No spaces allowed.
​
description
string
required
Human-readable description of what the tool does. The LLM uses this to decide when to call the tool, so be specific (e.g. “Look up the shipping status of a customer order by order ID”).
​
type
string
required
Tool type. Supported values: function, webhook.
​
definition
object
required
Tool definition following the OpenAI function calling schema. Must include name, description, and parameters (JSON Schema format).
Example
{
  "name": "check_order_status",
  "description": "Look up the current status of a customer order",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The unique order identifier"
      }
    },
    "required": ["order_id"]
  }
}

​
Response

​
success
boolean
Whether the request succeeded.
​
message
string
Human-readable status message.
​
data
object
The newly created tool object.
curl -X POST https://api.ravan.ai/api/v1/tools/ \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "check_order_status",
    "description": "Look up the current status of a customer order by order ID",
    "type": "function",
    "definition": {
      "name": "check_order_status",
      "description": "Look up the current status of a customer order",
      "parameters": {
        "type": "object",
        "properties": {
          "order_id": {
            "type": "string",
            "description": "The unique order identifier"
          }
        },
        "required": ["order_id"]
      }
    }
  }'

{
  "success": true,
  "message": "Tool created successfully",
  "data": {
    "id": "019d1fdb-3977-7bd5-ab27-8d3b37ddf4fc",
    "organizationId": "1268c1f0-19f3-47db-aefb-c16a7c3ace6e",
    "name": "check_order_status",
    "description": "Look up the current status of a customer order by order ID",
    "type": "function",
    "definition": {
      "name": "check_order_status",
      "description": "Look up the current status of a customer order",
      "parameters": {
        "type": "object",
        "properties": {
          "order_id": {
            "type": "string",
            "description": "The unique order identifier"
          }
        },
        "required": ["order_id"]
      }
    },
    "isActive": false
  }
}

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

Successful response

​
success
boolean
​
message
string
​
data
object