v1

latestOpenAPI 3.0.1MIT2026-07-26104203277.0 KB

Create a new web tool.

post/v1/voice-agents/web-tool

Request body

type'FUNCTION' | 'MCP' required

The type of the web tool.

namestring required

The name of the web tool.

descriptionstring

A description of what the web tool does.

asyncboolean

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

paramsobject

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 request

{
  "type": "FUNCTION",
  "name": "Weather API Tool",
  "description": "A tool that fetches current weather information for a given location.",
  "async": true,
  "toolSettings": {
    "serverUrl": "https://api.example.com/webhook",
    "authToken": "bearer_token_12345",
    "timeOut": 15,
    "methodType": "POST",
    "httpHeaders": {
      "Content-Type": "application/json",
      "Authorization": "Bearer token"
    },
    "pathParameters": {
      "userId": "12345"
    }
  },
  "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"
    ]
  }
}

Response

Successful response

successboolean

messagestring

Example response

{
  "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": {
      "httpHeaders": {
        "Content-Type": "application/json",
        "Authorization": "Bearer token"
      },
      "pathParameters": {
        "userId": "12345"
      },
      "serverUrl": "https://api.example.com/webhook",
      "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."
      }
    ]
  }
}