#Tools Configuration API

Manage tool configurations available to Agents, including provider settings and usage monitoring for search tools, code tools, and more.

Base Path: /v1/tools/configurations

#Tool Configuration Management

#List Tool Configurations

GET /v1/tools/configurations

#Query Parameters

Parameter	Type	Description
`page`	number	Page number, default 1
`limit`	number	Items per page, default 20, max 100
`enabled`	boolean	Filter by enabled status
`toolName`	string	Filter by tool name

#Response

json{
  "data": [
    {
      "id": "config_xxx",
      "organizationId": "org_xxx",
      "toolName": "web-search",
      "enabled": true,
      "provider": "exa",
      "usageLimits": {
        "maxCallsPerDay": 1000,
        "maxCallsPerMonth": 30000
      },
      "usageStats": {
        "callsToday": 45,
        "callsThisMonth": 1200,
        "remainingToday": 955,
        "remainingThisMonth": 28800
      },
      "createdAt": "2026-01-05T08:00:00Z",
      "updatedAt": "2026-02-10T12:00:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

#Get Tool Configuration Details

GET /v1/tools/configurations/:configId

#Response

json{
  "id": "config_xxx",
  "organizationId": "org_xxx",
  "toolName": "web-search",
  "enabled": true,
  "config": {
    "provider": "exa",
    "apiKey": "***",
    "usageLimits": {
      "maxCallsPerDay": 1000,
      "maxCallsPerMonth": 30000
    }
  },
  "usageLimits": {
    "maxCallsPerDay": 1000,
    "maxCallsPerMonth": 30000
  },
  "metadata": {},
  "createdAt": "2026-01-05T08:00:00Z",
  "updatedAt": "2026-02-10T12:00:00Z"
}

Note: The apiKey field in the response is masked and displayed as ***.

#Create Tool Configuration

POST /v1/tools/configurations

Required Permission: tools:create (admin or user role)

#Request Body

json{
  "toolName": "web-search",
  "config": {
    "provider": "exa",
    "apiKey": "your-provider-api-key",
    "usageLimits": {
      "maxCallsPerDay": 500,
      "maxCallsPerMonth": 15000
    }
  },
  "enabled": true
}

Field	Type	Required	Description
`toolName`	string	Yes	Tool name
`config`	object	No	Tool configuration
`config.provider`	string	No	Provider, default `builtin`
`config.apiKey`	string	No	Provider API Key
`enabled`	boolean	No	Whether enabled, default true

#Response

HTTP 201 Created

json{
  "id": "config_xxx",
  "organizationId": "org_xxx",
  "toolName": "web-search",
  "enabled": true,
  "createdAt": "2026-02-20T08:00:00Z"
}

#Update Tool Configuration

PATCH /v1/tools/configurations/:configId

Required Permission: tools:update (admin or user role)

#Request Body

json{
  "enabled": false,
  "config": {
    "apiKey": "new-api-key"
  }
}

#Delete Tool Configuration

DELETE /v1/tools/configurations/:configId

Required Permission: tools:delete (admin role only)

#Response

json{
  "id": "config_xxx",
  "deleted": true
}

#Usage Statistics

#Get Current Usage

GET /v1/tools/configurations/:configId/usage

#Response

json{
  "toolConfigId": "config_xxx",
  "toolName": "web-search",
  "provider": "exa",
  "usage": {
    "today": {
      "calls": 45,
      "limit": 1000,
      "remaining": 955,
      "percentage": 4.5,
      "successRate": 98.5
    },
    "thisMonth": {
      "calls": 1200,
      "limit": 30000,
      "remaining": 28800,
      "percentage": 4.0,
      "successRate": 97.8
    }
  },
  "lastResetAt": "2026-02-20T00:00:00Z",
  "nextResetAt": "2026-02-21T00:00:00Z"
}

#Get Usage History

GET /v1/tools/configurations/:configId/usage/history

#Query Parameters

Parameter	Type	Description
`startDate`	string	Start date (ISO format), default 30 days ago
`endDate`	string	End date (ISO format), default current time

#Response

json{
  "toolConfigId": "config_xxx",
  "toolName": "web-search",
  "period": {
    "start": "2026-01-21T00:00:00Z",
    "end": "2026-02-20T00:00:00Z"
  },
  "history": [
    {
      "date": "2026-02-19",
      "calls": 120,
      "successRate": 99.2,
      "errorCount": 1,
      "avgDuration": 450
    }
  ],
  "summary": {
    "totalCalls": 3500,
    "avgSuccessRate": 98.5,
    "avgDuration": 0,
    "totalErrors": 52
  }
}

#Testing and Validation

#Test Tool Configuration

POST /v1/tools/configurations/:configId/test

Required Permission: tools:update

Test whether a tool configuration is valid.

#Response

json{
  "success": true,
  "results": [
    {
      "title": "Configuration test",
      "url": "",
      "content": "Tool \"web-search\" (exa) configuration is valid."
    }
  ],
  "duration": 150,
  "provider": "exa"
}

#Validate API Key

POST /v1/tools/configurations/validate

Required Permission: tools:create

Validate the validity of a provider API Key.

#Request Body

json{
  "provider": "exa",
  "apiKey": "your-api-key"
}

#Response

json{
  "valid": true,
  "provider": "exa",
  "quotaInfo": {
    "plan": "unknown",
    "remaining": 0,
    "limit": 0
  }
}

#Custom Tools API

Create and manage custom tools supporting HTTP Webhook and JavaScript sandbox execution. Custom tools can be bound to Agents and automatically invoked by the LLM during conversations.

Base Path: /v1/custom-tools

#Tool Types

Type	Description
`http`	Call external HTTP endpoints (webhook mode), supports sync and async execution
`code`	Execute JavaScript code snippets in a Node.js sandbox

#Create Custom Tool

POST /v1/custom-tools

#HTTP Type Tool Request Body

json{
  "name": "get-weather",
  "description": "Get weather information for a specific city",
  "toolType": "http",
  "inputSchema": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "City name"
      }
    },
    "required": ["city"]
  },
  "endpoint": {
    "url": "https://api.example.com/weather",
    "timeoutMs": 5000,
    "auth": {
      "type": "bearer",
      "token": "your-api-token"
    }
  },
  "executionMode": "sync"
}

#Code Type Tool Request Body

json{
  "name": "calculate-price",
  "description": "Calculate price based on quantity and discount",
  "toolType": "code",
  "inputSchema": {
    "type": "object",
    "properties": {
      "quantity": {
        "type": "number",
        "description": "Quantity"
      },
      "discount": {
        "type": "number",
        "description": "Discount ratio (0-1)"
      }
    },
    "required": ["quantity"]
  },
  "codeSnippet": "const price = 99.9;\nconst total = price * args.quantity * (1 - (args.discount || 0));\nreturn { total: total.toFixed(2), currency: 'USD' };",
  "timeoutMs": 5000
}

#Field Reference

Field	Type	Required	Description
`name`	string	Yes	Tool name (unique within organization)
`description`	string	Yes	Tool description (used by LLM to understand purpose)
`toolType`	string	Yes	`http` or `code`
`inputSchema`	object	Yes	JSON Schema format parameter definition
`endpoint`	object	http only	HTTP endpoint configuration
`endpoint.url`	string	Yes	Request URL
`endpoint.timeoutMs`	number	No	Timeout in milliseconds, default 5000
`endpoint.auth`	object	No	Authentication configuration
`codeSnippet`	string	code only	JavaScript code snippet
`timeoutMs`	number	No	Execution timeout (ms), default 5000, max 30000
`executionMode`	string	No	`sync` (default) or `async`

#Authentication Types

Type	Fields	Description
`none`	-	No authentication
`api_key`	`header`, `value`	Custom header authentication
`bearer`	`token`	Bearer Token authentication
`basic`	`username`, `password`	HTTP Basic authentication

#Response

HTTP 201 Created

#List Custom Tools

GET /v1/custom-tools

Returns all custom tools for the current organization.

#Get Custom Tool Details

GET /v1/custom-tools/:toolId

#Update Custom Tool

PATCH /v1/custom-tools/:toolId

Supports partial updates, same fields as the create endpoint.

#Delete Custom Tool

DELETE /v1/custom-tools/:toolId

#Response

json{
  "success": true
}

#Test Custom Tool

POST /v1/custom-tools/:toolId/test

Test tool execution with given arguments.

#Request Body

json{
  "arguments": {
    "city": "Shanghai"
  }
}

#Response

json{
  "success": true,
  "content": "{\"temperature\": 22, \"condition\": \"sunny\"}",
  "duration": 350
}

#Binding Custom Tools to Agents

Bind custom tools to an Agent via the Agent update endpoint:

PATCH /v1/agents/:agentId

json{
  "settings": {
    "toolsEnabled": true,
    "customToolIds": ["tool-uuid-1", "tool-uuid-2"]
  }
}

Once bound, the Agent will automatically recognize and invoke associated custom tools during conversations.