Skip to main content

​
Create Tool

curl -X POST "https://your-instance.com/api/tools/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my_custom_tool",
    "name": "My Custom Tool",
    "content": "class Tools:\n    def calculator(self, expression: str) -> str:\n        return str(eval(expression))",
    "meta": {
      "description": "A custom calculator tool"
    },
    "access_grants": []
  }'
Create a new tool. Requires workspace.tools or workspace.tools_import permission for non-admin users.

​
Request Body

​
id
string
required
Unique identifier for the tool. Must be alphanumeric with underscores only (will be converted to lowercase).
​
name
string
required
Display name for the tool
​
content
string
required
Python source code for the tool. Must define a Tools class with tool methods. The system will:
  • Replace imports with internal versions
  • Load and validate the tool module
  • Extract tool specifications from the class
  • Parse frontmatter manifest
​
meta
object
required
Tool metadata
​
access_grants
array
Access control configuration

​
Response

Returns the created ToolResponse object with ID, metadata, and specifications.

​
Get Tool by ID

curl -X GET "https://your-instance.com/api/tools/id/my_tool" \
  -H "Authorization: Bearer YOUR_API_KEY"
Retrieve a specific tool by ID. Requires read access to the tool.

​
Path Parameters

​
id
string
required
The tool identifier

​
Response

Returns ToolAccessResponse with the complete tool data and write_access flag.

​
Update Tool

curl -X POST "https://your-instance.com/api/tools/id/my_tool/update" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my_tool",
    "name": "Updated Tool Name",
    "content": "class Tools:\n    pass",
    "meta": {
      "description": "Updated description"
    }
  }'
Update an existing tool. Requires write access (creator, admin, or write grant).

​
Request Body

Same as Create Tool request body.

​
Update Tool Access

curl -X POST "https://your-instance.com/api/tools/id/my_tool/access/update" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "access_grants": [
      {
        "principal_type": "user",
        "principal_id": "user123",
        "permission": "read"
      },
      {
        "principal_type": "group",
        "principal_id": "group456",
        "permission": "write"
      }
    ]
  }'
Update access control for a tool. Requires write access.

​
Request Body

​
access_grants
array
required
Array of access grant objects. Replaces existing grants.
Note: Public sharing grants are filtered based on sharing.public_tools permission.

​
Delete Tool

curl -X DELETE "https://your-instance.com/api/tools/id/my_tool/delete" \
  -H "Authorization: Bearer YOUR_API_KEY"
Delete a tool. Requires write access. Also removes the tool from cache and revokes all access grants.

​
Response

​
result
boolean
true if deletion was successful, false otherwise

​
Valve Management

​
Get Tool Valves

curl -X GET "https://your-instance.com/api/tools/id/my_tool/valves" \
  -H "Authorization: Bearer YOUR_API_KEY"
Retrieve the current valve configuration for a tool.

​
Get Valves Schema

curl -X GET "https://your-instance.com/api/tools/id/my_tool/valves/spec" \
  -H "Authorization: Bearer YOUR_API_KEY"
Retrieve the valve schema definition (if the tool defines a Valves class).

​
Update Tool Valves

curl -X POST "https://your-instance.com/api/tools/id/my_tool/valves/update" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "new_value",
    "enabled": true
  }'
Update valve configuration. Requires write access.

​
User Valves

​
Get User Valves

curl -X GET "https://your-instance.com/api/tools/id/my_tool/valves/user" \
  -H "Authorization: Bearer YOUR_API_KEY"
Retrieve user-specific valve values for the authenticated user.

​
Get User Valves Schema

curl -X GET "https://your-instance.com/api/tools/id/my_tool/valves/user/spec" \
  -H "Authorization: Bearer YOUR_API_KEY"
Retrieve the user valve schema definition (if the tool defines a UserValves class).

​
Update User Valves

curl -X POST "https://your-instance.com/api/tools/id/my_tool/valves/user/update" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "preference": "value"
  }'
Update user-specific valve values. Stored in user settings.

​
Load Tool from URL

curl -X POST "https://your-instance.com/api/tools/load/url" \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://github.com/user/repo/blob/main/tool.py"
  }'
Load a tool from a GitHub URL. Supports both file and folder URLs. Requires admin privileges.

​
Request Body

​
url
string
required
GitHub URL to the tool file or folder. URLs are automatically converted to raw.githubusercontent.com format.

​
Response

​
name
string
Suggested tool name extracted from the filename/folder
​
content
string
Tool source code

​
Python Tool Pattern

Tools should follow this pattern: 
"""
title: My Tool
author: Your Name
version: 1.0.0
"""

from pydantic import BaseModel, Field

class Valves(BaseModel):
    # Optional: Define configuration parameters
    api_key: str = Field(default="", description="API Key")

class UserValves(BaseModel):
    # Optional: Define user-specific parameters
    enabled: bool = Field(default=True, description="Enable tool")

class Tools:
    def __init__(self):
        self.valves = Valves()
    
    def my_function(self, param: str) -> str:
        """
        Description of what this function does.
        
        :param param: Parameter description
        :return: Return value description
        """
        return f"Result: {param}"
The system automatically:
  • Extracts tool specifications from the Tools class methods
  • Parses frontmatter as manifest
  • Validates valve schemas
  • Generates API documentation from docstrings

​
Error Responses

400 Bad Request
  • Invalid tool ID format
  • Tool ID already exists
  • Invalid Python code
  • Failed to load tool module
401 Unauthorized
  • Missing authentication
  • Insufficient permissions
404 Not Found
  • Tool does not exist

​
Authentication & Permissions

  • Most operations require verified user authentication
  • Creating tools requires workspace.tools or workspace.tools_import permission
  • Exporting tools requires workspace.tools_export permission
  • Write operations require tool ownership, write grant, or admin privileges
  • Loading from URL requires admin privileges

Build docs developers (and LLMs) love

Get started for freeTalk to us