---
title: "Create Web Tool"
method: POST
path: "/v2/voice-agents/web-tool"
---

# Create Web Tool

`POST /v2/voice-agents/web-tool`

Creates a new web tool for a project. Web tools can be of type FUNCTION, MCP, or WEB_TOOL.

## Request body

- CreateWebToolRequestV2
  - `type` 'FUNCTION' | 'MCP' | 'WEB_TOOL', required — The type of web tool to create
  - `name` string, required — The name of the web tool
  - `description` string — A description of what the web tool does
  - `collectionId` string, uuid — Optional collection ID to group the web tool
  - `async` boolean — Whether the tool runs asynchronously. Required for FUNCTION type, not allowed for MCP type.
  - `toolSettings` ToolSettings — Server configuration for the web tool. Required for FUNCTION and MCP types, not allowed for WEB_TOOL type.
    - `serverUrl` string, uri, required — The URL of the server endpoint
    - `methodType` string, required — The HTTP method type
    - `authToken` string, nullable — Optional authentication token
    - `timeOut` number — Request timeout in seconds (1-15)
    - `httpHeaders` object — Custom HTTP headers to include in requests
    - `pathParameters` object — Path parameters for the URL
  - `messages` WebToolMessage[] — Messages to display during tool execution
    - `type` 'REQUEST_START' | 'REQUEST_COMPLETE', required — The type of message. Each type can only appear once.
    - `content` string, required — The message content to display
  - `params` ParamsSchema — OpenAPI-style schema defining the parameters for the web tool. Not allowed for MCP type.
    - `type` 'object' — Must be 'object'
    - `properties` object — The properties of the parameters schema. Each property must have a description.
    - `required` string[] — List of required property names

## Response `200`

Web tool created successfully

- CreateWebToolResponseV2
  - `success` boolean
  - `message` string
  - `messageKey` string
  - `data` WebToolData
    - `id` string, uuid — The unique identifier of the web tool
    - `persistentId` string, uuid, nullable — The persistent ID used for versioning
    - `version` integer — The version number of the web tool
    - `name` string — The name of the web tool
    - `type` 'FUNCTION' | 'MCP' | 'WEB_TOOL' — The type of web tool
    - `userId` string, uuid — The ID of the user who created the tool
    - `projectId` string, uuid — The ID of the project
    - `isActive` boolean — Whether the web tool is active
    - `async` boolean — Whether the tool runs asynchronously
    - `description` string, nullable — Description of the web tool
    - `collectionId` string, uuid, nullable — The collection ID if grouped
    - `toolSettings` object, nullable — Tool server settings (null for WEB_TOOL type)
      - `httpHeaders` object, nullable — Custom HTTP headers
      - `pathParameters` object, nullable — URL path parameters
      - `serverUrl` string, nullable — The server endpoint URL
      - `timeout` number, nullable — Request timeout in seconds
      - `authToken` string, nullable — Authentication token
      - `methodType` string, nullable — HTTP method type
    - `params` object, nullable — The parameters schema in OpenAPI format
    - `messages` WebToolMessage[] — Messages to display during tool execution
      - `type` 'REQUEST_START' | 'REQUEST_COMPLETE', required — The type of message. Each type can only appear once.
      - `content` string, required — The message content to display

## Other responses

- `400` — Validation error
- `401` — Unauthorized
- `500` — Server Side Error

---

[API](https://skmtc.net/tryhamsa/apis/hamsa-api.md) · [All operations](https://skmtc.net/tryhamsa/apis/hamsa-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tryhamsa/hamsa-api/versions/ecbeb5d8dc13/schema)