Skip to main content
POST
/
v1
/
voice-agents
/
web-tool
Create a new web tool.
curl --request POST \
  --url https://api.tryhamsa.com/v1/voice-agents/web-tool \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "FUNCTION",
  "name": "Weather API Tool",
  "toolSettings": {
    "serverUrl": "https://api.example.com/webhook",
    "methodType": "POST",
    "authToken": "bearer_token_12345",
    "timeOut": 15,
    "httpHeaders": {
      "Content-Type": "application/json",
      "Authorization": "Bearer token"
    },
    "pathParameters": {
      "userId": "12345"
    }
  },
  "description": "A tool that fetches current weather information for a given location.",
  "async": true,
  "messages": [
    {
      "type": "system",
      "content": "You are a helpful weather assistant."
    }
  ],
  "params": {
    "type": "object",
    "properties": {
      "test": {
        "type": "number",
        "description": "Hello world from Hamsa AI!"
      }
    },
    "required": [
      "test"
    ]
  }
}
'
{
  "success": false,
  "message": "success",
  "data": {
    "id": "d949f13f-40d2-4e48-ac86-b66633070603",
    "persistentId": "cmjx8qzw0000004kz3jek1ktu",
    "version": 1,
    "name": "Weather API Tool",
    "type": "FUNCTION",
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "projectId": "d949f13f-40d2-4e48-ac86-b66633070603",
    "isActive": true,
    "async": true,
    "description": "A tool that fetches current weather information for a given location.",
    "collectionId": "550e8400-e29b-41d4-a716-446655440000",
    "toolSettings": {
      "serverUrl": "https://api.example.com/webhook",
      "httpHeaders": {
        "Content-Type": "application/json",
        "Authorization": "Bearer token"
      },
      "pathParameters": {
        "userId": "12345"
      },
      "timeout": 5000,
      "authToken": "bearer_token_12345",
      "methodType": "POST"
    },
    "params": {
      "location": {
        "type": "string",
        "description": "The location to get weather for"
      }
    },
    "messages": [
      {
        "type": "system",
        "content": "You are a helpful weather assistant."
      }
    ]
  }
}

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 the web tool.

Available options:
FUNCTION,
MCP
Example:

"FUNCTION"

​
name
string
required

The name of the web tool.

Required string length: 1 - 250
Example:

"Weather API Tool"

​
toolSettings
object
required

Server configuration settings for the web tool.

​
description
string

A description of what the web tool does.

Required string length: 1 - 1000
Example:

"A tool that fetches current weather information for a given location."

​
async
boolean

Whether the tool should run asynchronously. Required when type is FUNCTION, not allowed when type is MCP.

Example:

true

​
messages
object[]

Array of message configurations for the web tool. Each message type must be unique.

Example:
[
  {
    "type": "system",
    "content": "You are a helpful weather assistant."
  }
]
​
params
object

Parameter schema definition for the web tool. Not allowed when type is MCP. This field is a recursive OpenAPI-style shape with 'type', 'properties', 'required', 'items', ...etc. Please refer to the OpenAPI specification for more information.

Example:
{
  "type": "object",
  "properties": {
    "test": {
      "type": "number",
      "description": "Hello world from Hamsa AI!"
    }
  },
  "required": ["test"]
}

Response

Successful response

​
success
boolean
default:false
​
message
string
default:success
​
data
object