Create Tool

POST /api/v1/tools/ — request parameters and responses from the Menace Voice API schema.

2 min read

post/api/v1/tools

Request example

curl --request POST \
  --url https://voice.menaceui.com/api/v1/tools \
  --header 'authorization: <string>' \
  --header 'X-API-Key: <string>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "description": "<string>",
  "category": "http_api",
  "icon": "globe",
  "icon_color": "#3B82F6",
  "definition": {
    "schema_version": 1,
    "type": "http_api",
    "config": {
      "method": "GET",
      "url": "<string>",
      "headers": {},
      "credential_uuid": "<string>",
      "parameters": [
        {
          "name": "<string>",
          "type": "string",
          "description": "<string>",
          "required": true
        }
      ],
      "preset_parameters": [
        {
          "name": "<string>",
          "type": "string",
          "value_template": "<string>",
          "required": true
        }
      ],
      "timeout_ms": 5000,
      "customMessage": "<string>",
      "customMessageType": "text",
      "customMessageRecordingId": "<string>",
      "body_template": {}
    }
  }
}'

Response

{
  "id": 1,
  "tool_uuid": "<string>",
  "name": "<string>",
  "description": "<string>",
  "category": "<string>",
  "icon": "<string>",
  "icon_color": "<string>",
  "status": "<string>",
  "definition": {},
  "created_at": "2026-08-10T12:00:00Z",
  "updated_at": "2026-08-10T12:00:00Z",
  "created_by": {
    "id": 1,
    "provider_id": "<string>"
  }
}

post/api/v1/tools

See authentication for workspace API access. Public embed and artifact endpoints use their documented session or access tokens.

Headers

authorizationstring · null#

X-API-Keystring · null#

Body

application/json

namestringrequired#

Display name for the tool.

Length: max 255

descriptionstring · null#

Description shown to the agent when deciding whether to call it.

Show child attributes

Any of

categoryenum<string>#

Tool category. Must match definition.type.

Default: "http_api"

Options:http_apiend_calltransfer_callcalculatorcurrent_timenativeintegrationmcp

iconstring · null#

Lucide icon identifier.

Default: "globe"

Show child attributes

Any of

icon_colorstring · null#

Hex color for the tool icon.

Default: "#3B82F6"

Show child attributes

Any of

definitionobjectrequired#

Typed tool definition.

Show child attributes

One of

schema_versioninteger#

Schema version.

Default: 1

typeenum<string>required#

Tool type.

Options:http_api

configobjectrequired#

Configuration for HTTP API tools.

Show child attributes

methodenum<string>required#

HTTP method to use for the request.

Options:GETPOSTPUTPATCHDELETE

urlstringrequired#

Target HTTP or HTTPS URL.

headersobject · null#

Static headers to include with every request.

Show child attributes

credential_uuidstring · null#

Reference to an external credential for request authentication.

Show child attributes

parametersobject[] · null#

Parameters the model must provide when calling this tool.

Show child attributes

preset_parametersobject[] · null#

Parameters injected by Menace Voice from fixed values or workflow context templates.

Show child attributes

timeout_msinteger · null#

Request timeout in milliseconds.

Default: 5000

Show child attributes

customMessagestring · null#

Custom message to play after tool execution.

Show child attributes

customMessageTypeenum<string> · null#

Type of custom message.

Show child attributes

customMessageRecordingIdstring · null#

Recording ID for an audio custom message.

Show child attributes

body_templateobject · null#

Optional JSON body template for POST, PUT, and PATCH requests.

Show child attributes

schema_versioninteger#

Schema version.

Default: 1

typeenum<string>required#

Tool type.

Options:end_call

configobjectrequired#

Configuration for End Call tools.

Show child attributes

messageTypeenum<string>#

Type of goodbye message.

Default: "none"

Options:nonecustomaudio

customMessagestring · null#

Custom message to play before ending the call.

Show child attributes

audioRecordingIdstring · null#

Recording ID for audio goodbye message.

Show child attributes

endCallReasonboolean#

When enabled, the model must provide a reason for ending the call. The reason is set as call disposition and added to call tags.

Default: false

endCallReasonDescriptionstring · null#

Description shown to the model for the reason parameter. Used only when endCallReason is enabled.

Show child attributes

schema_versioninteger#

Schema version.

Default: 1

typeenum<string>required#

Tool type.

Options:transfer_call

configobjectrequired#

Configuration for Transfer Call tools.

Show child attributes

destination_sourceenum<string>#

Whether the destination is static/template, resolved by HTTP, or selected by ordered gathered/initial-context mapping rules.

Default: "static"

Options:staticdynamiccontext_mapping

destinationstring#

Phone number, SIP endpoint, or template to transfer the call to, e.g. +1234567890, PJSIP/1234, or {{initial_context.transfer_destination}}.

Default: ""

messageTypeenum<string>#

Type of message to play before transfer.

Default: "none"

Options:nonecustomaudio

customMessagestring · null#

Custom message to play before transferring.

Show child attributes

audioRecordingIdstring · null#

Recording ID for audio message before transfer.

Show child attributes

timeoutinteger#

Maximum seconds to wait for the destination to answer.

Default: 30

Range: 5–120

call_dispositionstring · null#

Optional disposition to record after a successful transfer. When omitted, Menace Voice records its provider-specific transfer default.

Show child attributes

parametersobject[] · null#

Parameters the model may provide when calling this transfer tool, for example state, department, or transfer reason.

Show child attributes

resolverobject · null#

Optional resolver that determines transfer routing at call time.

Show child attributes

context_mappingobject · null#

Optional ordered context-to-destination routing rules.

Show child attributes

schema_versioninteger#

Schema version.

Default: 1

typeenum<string>required#

Tool type.

Options:calculator

schema_versioninteger#

Schema version.

Default: 1

typeenum<string>required#

Tool type.

Options:current_time

schema_versioninteger#

Schema version.

Default: 1

typeenum<string>required#

Tool type.

Options:mcp

configobjectrequired#

Configuration for a customer MCP server tool definition.

Show child attributes

transportenum<string>#

MCP transport protocol.

Default: "streamable_http"

Options:streamable_http

urlstringrequired#

MCP server URL. Must use http:// or https://.

credential_uuidstring · null#

Reference to an external credential for MCP server auth.

Show child attributes

tools_filterstring[]#

Allowlist of MCP tool names to expose. Empty exposes all tools.

timeout_secsinteger#

Connection timeout in seconds.

Default: 30

Range: >= 0

sse_read_timeout_secsinteger#

SSE read timeout in seconds.

Default: 300

Range: >= 0

discovered_toolsobject[]#

Server-managed cache of the MCP server's tool catalog [{name, description}]. Populated best-effort by the backend.

Responses

application/json

Successful Response

idintegerrequired#

tool_uuidstringrequired#

namestringrequired#

descriptionstring · nullrequired#

Show child attributes

Any of

categorystringrequired#

iconstring · nullrequired#

Show child attributes

Any of

icon_colorstring · nullrequired#

Show child attributes

Any of

statusstringrequired#

definitionobjectrequired#

created_atstringrequired#

updated_atstring · nullrequired#

Show child attributes

Any of

created_byobject · null#

Show child attributes

Any of

idintegerrequired#

provider_idstringrequired#

List Tools Get Tool