Tools

API Key Required

The Ultravox API requires an API key. For more details see Authentication.

Tools in Ultravox allow you to extend the capabilities of your AI agent by giving it access to external APIs and services. With tools, your AI can perform actions like fetching real-time data, interacting with databases, or integrating with third-party services, all while maintaining a natural conversation flow.

Tools in Ultravox are Different

Unlike using tools with single-generation LLM APIs, Ultravox actually calls your tool. This means you need to do a bit more work upfront in defining tools with the proper authentication and parameters.

Read Tools in Ultravox for loads of information about tool types, auth, and custom parameters.

Use ultravox-70B for Tools

While tools are supported across multiple variants of the Ultravox model, using tools with smaller models (i.e. 8B) typically don’t work well. YMMV. See available models for more info.

List Tools

GET /tools

Lists all available tools. Account scoped.

Parameters

cursor	Pagination cursor.

Request Body

None

Response

next	string	URL for the next page of results.
previous	string	URL for the previous page of results.
results	array	Array of objects. Each object contains: toolId, name, created, and definition (see the tool definition for details.)

Create Tool

POST /tools

Creates a new tool. Account scoped.

Parameters

None

Request Body

name required	string	The name of the tool. Maximum 40 characters.
definition required	object	A Tool definition.

Response

toolId	string	Unique identifier for the created tool.
name	string	The name of the tool.
created	string	Timestamp of when the tool was created.
definition	object	The definition of the Tool.

Get Tool

GET /tools/{tool_id}

Retrieves details of a specific tool. Account scoped.

Parameters

tool_id required	Unique identifier of the tool to retrieve.

Request Body

None

Response

toolId	string	Unique identifier for the tool.
name	string	The name of the tool.
created	string	Timestamp of when the tool was created.
definition	object	A Tool defintion object for the tool.

Update Tool

PUT /tools/{tool_id}

Replaces an existing tool. Updating a single field in a tool is not supported. The entire tool definition must be provided. Account scoped.

Parameters

tool_id required	Unique identifier of the tool to update.

Request Body

name required	string	The updated name of the tool. Maximum 40 characters.
definition required	object	The updated Tool definition of the tool.

Response

toolId	string	Unique identifier for the updated tool.
name	string	The updated name of the tool.
created	string	Timestamp of when the tool was originally created.
definition	object	The updated Tool definition for the tool.

Delete Tool

DELETE /tools/{tool_id}

Deletes a specific tool. Account scoped.

Parameters

tool_id required	Unique identifier of the tool to delete.

Request Body

None

Response

None

Examples

List All Tools

cURL

curl --request GET \
--url 'https://api.ultravox.ai/api/tools' \
--header 'X-API-Key: aBCDef.123456'

JavaScript

fetch('https://api.ultravox.ai/api/tools', {
  method: 'GET',
  headers: {
    'X-API-Key': 'aBCDef.123456'
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Response

{
  "next": null,
  "previous": null,
  "results": [
    {
      "toolId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "weather_api",
      "created": "2024-09-18T10:30:00Z",
      "definition": {
        "description": "Get current weather information for a given location",
        "dynamicParameters": [
          {
            "name": "location",
            "location": "PARAMETER_LOCATION_QUERY",
            "schema": {
              "type": "string",
              "description": "City name or ZIP code"
            },
            "required": true
          }
        ],
        "http": {
          "baseUrlPattern": "https://api.weatherservice.com/v1/current",
          "httpMethod": "GET"
        }
      }
    }
  ]
}

Create Tools from OpenAPI (Swagger) File

cURL

curl -X POST -F "file=@./<your_tools_file.yaml>;type=text/yaml" \
--url https://api.ultravox.ai/api/tools \
--header 'X-API-Key: aBCDef.123456'

Create a New Tool

cURL

curl --request POST \
--url 'https://api.ultravox.ai/api/tools' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: aBCDef.123456' \
--data '{
  "name": "stock_price",
  "definition": {
    "description": "Get the current stock price for a given symbol",
    "dynamicParameters": [
      {
        "name": "symbol",
        "location": "PARAMETER_LOCATION_QUERY",
        "schema": {
          "type": "string",
          "description": "Stock symbol (e.g., AAPL for Apple Inc.)"
        },
        "required": true
      }
    ],
    "http": {
      "baseUrlPattern": "https://api.stockmarket.com/v1/price",
      "httpMethod": "GET"
    }
  }
}'

JavaScript

const toolData = {
  name: "stock_price",
  definition: {
    description: "Get the current stock price for a given symbol",
    dynamicParameters: [
      {
        name: "symbol",
        location: "PARAMETER_LOCATION_QUERY",
        schema: {
          type: "string",
          description: "Stock symbol (e.g., AAPL for Apple Inc.)"
        },
        required: true
      }
    ],
    http: {
      baseUrlPattern: "https://api.stockmarket.com/v1/price",
      httpMethod: "GET"
    }
  }
};

fetch('https://api.ultravox.ai/api/tools', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'aBCDef.123456'
  },
  body: JSON.stringify(toolData)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Response

{
  "toolId": "7f1e3b78-c71e-4b1f-9c4a-b83f7683f0d2",
  "name": "stock_price",
  "created": "2024-09-18T14:15:22Z",
  "definition": {
    "description": "Get the current stock price for a given symbol",
    "dynamicParameters": [
      {
        "name": "symbol",
        "location": "PARAMETER_LOCATION_QUERY",
        "schema": {
          "type": "string",
          "description": "Stock symbol (e.g., AAPL for Apple Inc.)"
        },
        "required": true
      }
    ],
    "http": {
      "baseUrlPattern": "https://api.stockmarket.com/v1/price",
      "httpMethod": "GET"
    }
  }
}

Update an Existing Tool

cURL

curl --request PUT \
--url 'https://api.ultravox.ai/api/tools/7f1e3b78-c71e-4b1f-9c4a-b83f7683f0d2' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: aBCDef.123456' \
--data '{
  "name": "stock_price_v2",
  "definition": {
    "description": "Get the current stock price and company info for a given symbol",
    "dynamicParameters": [
      {
        "name": "symbol",
        "location": "PARAMETER_LOCATION_QUERY",
        "schema": {
          "type": "string",
          "description": "Stock symbol (e.g., AAPL for Apple Inc.)"
        },
        "required": true
      }
    ],
    "http": {
      "baseUrlPattern": "https://api.stockmarket.com/v2/price-and-info",
      "httpMethod": "GET"
    }
  }
}'

JavaScript

const updatedToolData = {
  name: "stock_price_v2",
  definition: {
    description: "Get the current stock price and company info for a given symbol",
    dynamicParameters: [
      {
        name: "symbol",
        location: "PARAMETER_LOCATION_QUERY",
        schema: {
          type: "string",
          description: "Stock symbol (e.g., AAPL for Apple Inc.)"
        },
        required: true
      }
    ],
    http: {
      baseUrlPattern: "https://api.stockmarket.com/v2/price-and-info",
      httpMethod: "GET"
    }
  }
};

fetch('https://api.ultravox.ai/api/tools/7f1e3b78-c71e-4b1f-9c4a-b83f7683f0d2', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'aBCDef.123456'
  },
  body: JSON.stringify(updatedToolData)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Response

{
  "toolId": "7f1e3b78-c71e-4b1f-9c4a-b83f7683f0d2",
  "name": "stock_price_v2",
  "created": "2024-09-18T14:15:22Z",
  "definition": {
    "description": "Get the current stock price and company info for a given symbol",
    "dynamicParameters": [
      {
        "name": "symbol",
        "location": "PARAMETER_LOCATION_QUERY",
        "schema": {
          "type": "string",
          "description": "Stock symbol (e.g., AAPL for Apple Inc.)"
        },
        "required": true
      }
    ],
    "http": {
      "baseUrlPattern": "https://api.stockmarket.com/v2/price-and-info",
      "httpMethod": "GET"
    }
  }
}