Manage Tools

Create, update, delete, and configure tools

Create Tool

POST /api/tools/create

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

Show meta properties

description · string

Description of what the tool does

manifest · object

Additional manifest data (will be populated from tool frontmatter)

access_grants · array

Access control configuration

Show access grant properties

principal_type · string

“user” or “group”

principal_id · string

User ID, group ID, or ”*” for all

permission · string

“read” or “write”

Response

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

Get Tool by ID

GET /api/tools/id/{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

POST /api/tools/id/{id}/update

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

POST /api/tools/id/{id}/access/update

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

DELETE /api/tools/id/{id}/delete

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

GET /api/tools/id/{id}/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

GET /api/tools/id/{id}/valves/spec

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

POST /api/tools/id/{id}/valves/update

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

GET /api/tools/id/{id}/valves/user

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

GET /api/tools/id/{id}/valves/user/spec

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

POST /api/tools/id/{id}/valves/user/update

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

POST /api/tools/load/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