Skip to main content
POST
Create a tool
Requires Editor, Admin, or Owner. Choose a typed definition for an HTTP API, end call, transfer call, calculator, or MCP tool. The request schema lists the configuration for each type. Tools with a stored credential, nonempty headers, or preset parameter values additionally require Admin or Owner. MCP configuration can contact the configured server to discover tools. Creating a tool does not automatically attach it to an agent. Each successful request creates another resource. Tools managed by an integration cannot be created, edited, duplicated, archived, or restored through the general tool endpoints; these attempts return 409. Do not set integration_provider or integration_id yourself. Manage Calendly access through its connection endpoints.

Authorizations

Authorization
string
header
required

Bandwidth Labs OAuth access token. Uses the user's selected workspace; the workspace header is not required. Do not also send an API key. Bearer-only operations may additionally require the Labs super_user role.

Headers

X-VOAI-ORGANIZATION-ID
string | null

Required with X-BW-LABS-AGENTS-API-KEY: the positive local workspace ID to access. The key owner must be a current member. Missing or invalid IDs return 400; non-member workspaces return 403. Not required for bearer authentication, which uses the user's selected workspace.

Body

application/json
definition
HttpApiToolDefinition · object
required
name
string
required
Maximum string length: 255
category
enum<string>
default:http_api
Available options:
http_api,
end_call,
transfer_call,
calculator,
native,
integration,
mcp
description
string | null
icon
string | null
default:globe
Maximum string length: 50
icon_color
string | null
default:#3B82F6
Maximum string length: 7

Response

Successful Response

category
string
required
created_at
string<date-time>
required
definition
Definition · object
required
description
string | null
required
icon
string | null
required
icon_color
string | null
required
id
integer
required
name
string
required
status
string
required
tool_uuid
string
required
updated_at
string<date-time> | null
required
created_by
CreatedByResponse · object | null