Skip to main content
POST
/
v2
/
voice-agents
/
web-tool
Create Web Tool
curl --request POST \
  --url https://api.tryhamsa.com/v2/voice-agents/web-tool \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "FUNCTION",
  "name": "Get Weather Data",
  "description": "Fetches current weather data for a given location",
  "collectionId": "48f7656f-098b-4c43-b165-7cfd2cc8ac30",
  "async": false,
  "toolSettings": {
    "serverUrl": "https://api.example.com/weather",
    "methodType": "GET",
    "authToken": "Bearer sk-...",
    "timeOut": 5,
    "httpHeaders": {
      "Content-Type": "application/json"
    },
    "pathParameters": {
      "city": "london"
    }
  },
  "messages": [
    {
      "type": "REQUEST_START",
      "content": "Fetching weather data..."
    }
  ],
  "params": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city name to get weather for"
      },
      "units": {
        "type": "string",
        "description": "Temperature units",
        "enum": [
          "celsius",
          "fahrenheit"
        ]
      }
    },
    "required": [
      "location"
    ]
  }
}
'
{
  "success": true,
  "message": "Web tool created successfully",
  "messageKey": "WebToolCreatedSuccessfully",
  "data": {
    "id": "48f7656f-098b-4c43-b165-7cfd2cc8ac30",
    "persistentId": "48f7656f-098b-4c43-b165-7cfd2cc8ac30",
    "version": 1,
    "name": "Get Weather Data",
    "type": "FUNCTION",
    "userId": "48f7656f-098b-4c43-b165-7cfd2cc8ac30",
    "projectId": "48f7656f-098b-4c43-b165-7cfd2cc8ac30",
    "isActive": true,
    "async": false,
    "description": "Fetches current weather data for a given location",
    "collectionId": "48f7656f-098b-4c43-b165-7cfd2cc8ac30",
    "toolSettings": {
      "httpHeaders": {},
      "pathParameters": {},
      "serverUrl": "<string>",
      "timeout": 123,
      "authToken": "<string>",
      "methodType": "<string>"
    },
    "params": {},
    "messages": [
      {
        "type": "REQUEST_START",
        "content": "Fetching weather data..."
      }
    ]
  }
}

Authorizations

​
Authorization
string
header
required

Pass the API key in the Authorization header, You need to put Token keyword before the API key. e.g. 'Authorization: Token '

Body

application/json
​
type
enum<string>
required

The type of web tool to create

Available options:
FUNCTION,
MCP,
WEB_TOOL
Example:

"FUNCTION"

​
name
string
required

The name of the web tool

Maximum string length: 250
Example:

"Get Weather Data"

​
description
string

A description of what the web tool does

Maximum string length: 1000
Example:

"Fetches current weather data for a given location"

​
collectionId
string<uuid>

Optional collection ID to group the web tool

Example:

"48f7656f-098b-4c43-b165-7cfd2cc8ac30"

​
async
boolean

Whether the tool runs asynchronously. Required for FUNCTION type, not allowed for MCP type.

Example:

false

​
toolSettings
object

Server configuration for the web tool. Required for FUNCTION and MCP types, not allowed for WEB_TOOL type.

​
messages
object[]

Messages to display during tool execution

​
params
object

OpenAPI-style schema defining the parameters for the web tool. Not allowed for MCP type.

Response

Web tool created successfully

​
success
boolean
Example:

true

​
message
string
Example:

"Web tool created successfully"

​
messageKey
string
Example:

"WebToolCreatedSuccessfully"

​
data
object