Tools

Overview

Tools extend the capabilities of AI agents by providing custom functions they can invoke. The Tools API allows you to programmatically manage custom tools for your chatflows.

All tool endpoints require JWT authentication. See Authentication for details.

List All Tools

Retrieve all tools in your workspace.

GET /api/v1/tools

curl -X GET http://localhost:3000/api/v1/tools \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Query Parameters

page

number

default:"1"

Page number for pagination

limit

number

default:"10"

Number of items per page

Response

[
  {
    "id": "tool-uuid",
    "name": "Weather Tool",
    "description": "Get current weather for a city",
    "color": "#3B82F6",
    "iconSrc": "https://example.com/weather-icon.png",
    "schema": "{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}}}",
    "func": "async function getWeather(city) { ... }",
    "workspaceId": "workspace-id",
    "createdDate": "2024-03-15T10:30:00.000Z",
    "updatedDate": "2024-03-15T10:30:00.000Z"
  }
]

string

required

Unique identifier for the tool

name

string

required

Display name of the tool

description

string

required

Description of what the tool does (shown to the AI)

color

string

required

Hex color code for the tool’s visual representation

iconSrc

string

URL to an icon image for the tool

schema

string

JSON schema defining the tool’s input parameters

func

string

JavaScript function code that executes when the tool is called

workspaceId

string

required

ID of the workspace this tool belongs to

Get Tool by ID

Retrieve a specific tool by its ID.

GET /api/v1/tools/:id

curl -X GET http://localhost:3000/api/v1/tools/TOOL_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Path Parameters

string

required

The unique identifier of the tool

Response

Returns a single tool object with the same structure as shown in the list response.

Create Tool

Create a new custom tool.

POST /api/v1/tools

curl -X POST http://localhost:3000/api/v1/tools \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Calculator",
    "description": "Perform mathematical calculations",
    "color": "#10B981",
    "schema": "{\"type\":\"object\",\"properties\":{\"expression\":{\"type\":\"string\",\"description\":\"Mathematical expression to evaluate\"}}}",
    "func": "async function calculate(expression) { return eval(expression); }"
  }'

Request Body

name

string

required

Name of the tool

description

string

required

Description of what the tool does. This is shown to the AI agent to help it decide when to use the tool.

color

string

required

Hex color code for visual representation (e.g., #3B82F6)

iconSrc

string

URL to an icon image for the tool

schema

string

JSON schema (as a string) defining the tool’s input parameters

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "City name"
    },
    "units": {
      "type": "string",
      "enum": ["celsius", "fahrenheit"],
      "description": "Temperature units"
    }
  },
  "required": ["city"]
}

func

string

JavaScript function code that executes when the tool is called

async function getWeather(city, units = 'celsius') {
  const apiKey = 'YOUR_API_KEY';
  const response = await fetch(
    `https://api.weather.com/v1/current?city=${city}&units=${units}&key=${apiKey}`
  );
  const data = await response.json();
  return `The current temperature in ${city} is ${data.temp}°${units === 'celsius' ? 'C' : 'F'}`;
}

Response

{
  "id": "tool-uuid",
  "name": "Calculator",
  "description": "Perform mathematical calculations",
  "color": "#10B981",
  "schema": "{...}",
  "func": "async function calculate(expression) { ... }",
  "workspaceId": "workspace-id",
  "createdDate": "2024-03-15T10:30:00.000Z",
  "updatedDate": "2024-03-15T10:30:00.000Z"
}

Update Tool

Update an existing tool.

PUT /api/v1/tools/:id

curl -X PUT http://localhost:3000/api/v1/tools/TOOL_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "color": "#F59E0B"
  }'

Path Parameters

string

required

The unique identifier of the tool to update

Request Body

Include only the fields you want to update. All fields from the create endpoint are supported.

Response

Returns the updated tool object.

Delete Tool

Delete a tool permanently.

DELETE /api/v1/tools/:id

curl -X DELETE http://localhost:3000/api/v1/tools/TOOL_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Path Parameters

string

required

The unique identifier of the tool to delete

Response

{
  "message": "Tool deleted successfully"
}

Deleting a tool will break any chatflows currently using it. Ensure no active flows depend on the tool before deletion.

Tool Function Guidelines

When creating tool functions, follow these best practices:

Use Async Functions

Always define tools as async functions, even if they don’t perform asynchronous operations:

async function myTool(param) {
  // Your code here
  return result;
}

Handle Errors Gracefully

Wrap your code in try-catch blocks and return user-friendly error messages:

async function weatherTool(city) {
  try {
    const response = await fetch(`https://api.weather.com/v1/${city}`);
    if (!response.ok) {
      return `Error: Unable to fetch weather for ${city}`;
    }
    const data = await response.json();
    return `Temperature: ${data.temp}°C`;
  } catch (error) {
    return `Error: ${error.message}`;
  }
}

Return Descriptive Results

Return results in a format that’s easy for the AI to understand and present to users:

// Good - descriptive result
return `The stock price of ${symbol} is $${price} (${change > 0 ? '+' : ''}${change}%)`;

// Bad - just raw data
return { price: 150.25, change: 2.3 };

Validate Input Parameters

Always validate input parameters before using them:

async function calculateTool(expression) {
  if (!expression || typeof expression !== 'string') {
    return 'Error: expression must be a non-empty string';
  }
  // Process expression
}

Tool Schema Examples

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search query"
    }
  },
  "required": ["query"]
}

Complete Tool Examples

// Tool configuration
{
  "name": "Get Weather",
  "description": "Get current weather information for any city",
  "color": "#3B82F6",
  "schema": JSON.stringify({
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "City name"
      },
      "units": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "default": "celsius"
      }
    },
    "required": ["city"]
  }),
  "func": `async function getWeather(city, units = 'celsius') {
    try {
      const apiKey = process.env.WEATHER_API_KEY;
      const response = await fetch(
        \`https://api.openweathermap.org/data/2.5/weather?q=\${city}&units=\${units === 'celsius' ? 'metric' : 'imperial'}&appid=\${apiKey}\`
      );
      
      if (!response.ok) {
        return \`Unable to find weather data for \${city}\`;
      }
      
      const data = await response.json();
      const temp = Math.round(data.main.temp);
      const condition = data.weather[0].description;
      
      return \`The weather in \${city} is \${condition} with a temperature of \${temp}°\${units === 'celsius' ? 'C' : 'F'}\`;
    } catch (error) {
      return \`Error fetching weather: \${error.message}\`;
    }
  }`
}

Code Examples

// Create a tool
const newTool = await fetch('http://localhost:3000/api/v1/tools', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Calculator',
    description: 'Perform mathematical calculations',
    color: '#10B981',
    schema: JSON.stringify({
      type: 'object',
      properties: {
        expression: {
          type: 'string',
          description: 'Math expression to evaluate'
        }
      },
      required: ['expression']
    }),
    func: `async function calculate(expression) {
      try {
        const result = eval(expression);
        return \`Result: \${result}\`;
      } catch (error) {
        return 'Invalid expression';
      }
    }`
  })
}).then(res => res.json());

// List all tools
const tools = await fetch('http://localhost:3000/api/v1/tools', {
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  }
}).then(res => res.json());

// Update a tool
const updated = await fetch(`http://localhost:3000/api/v1/tools/${toolId}`, {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    description: 'Updated calculator tool description'
  })
}).then(res => res.json());

Getting Started

Endpoints

Overview

List All Tools

Query Parameters

Response

Get Tool by ID

Path Parameters

Response

Create Tool

Request Body

Response

Update Tool

Path Parameters

Request Body

Response

Delete Tool

Path Parameters

Response

Tool Function Guidelines

Tool Schema Examples

Complete Tool Examples

Code Examples

Build docs developers (and LLMs) love

Getting Started

Endpoints

​Overview

​List All Tools

​Query Parameters

​Response

​Get Tool by ID

​Path Parameters

​Response

​Create Tool

​Request Body

​Response

​Update Tool

​Path Parameters

​Request Body

​Response

​Delete Tool

​Path Parameters

​Response

​Tool Function Guidelines

​Tool Schema Examples

​Complete Tool Examples

​Code Examples

Build docs developers (and LLMs) love

Overview

List All Tools

Query Parameters

Response

Get Tool by ID

Path Parameters

Response

Create Tool

Request Body

Response

Update Tool

Path Parameters

Request Body

Response

Delete Tool

Path Parameters

Response

Tool Function Guidelines

Tool Schema Examples

Complete Tool Examples

Code Examples