Base URL http://localhost:3333/api/ · Authentication · Conventions

Tools Routes

Base path: /api/tools

Get Orchestrator Tools

GET /orchestrator-tools

  • Authentication: Required
  • Description: Get all orchestrator tools (native, registry, and plugin tools)
  • Response:
{
  "tools": [
    {
      "id": "tool-name",
      "name": "Tool Name",
      "title": "Tool Title",
      "description": "Tool description",
      "category": "Data & Knowledge",
      "is_builtin": true,
      "is_plugin": false,
      "plugin_name": null
    }
  ]
}

Get Workflow Tools

GET /workflow-tools

  • Authentication: Required
  • Description: Get all tools for the workflow designer including plugins and custom tools
  • Response:
{
  "triggers": [
    {
      "type": "trigger-type",
      "title": "Trigger Title",
      "description": "Trigger description",
      "icon": "trigger-icon",
      "isPlugin": false
    }
  ],
  "actions": [
    {
      "type": "action-type",
      "title": "Action Title",
      "description": "Action description",
      "icon": "action-icon",
      "isPlugin": false
    }
  ],
  "utilities": [
    {
      "type": "utility-type",
      "title": "Utility Title",
      "description": "Utility description",
      "icon": "utility-icon",
      "isPlugin": false
    }
  ],
  "widgets": [],
  "controls": [],
  "custom": [
    {
      "id": "custom-tool-id",
      "name": "Custom Tool",
      "description": "Custom tool description"
    }
  ]
}

Get Plugin Tools Only

GET /plugins-only

  • Authentication: None
  • Description: Get only plugin tools (for real-time updates)
  • Response:
{
  "success": true,
  "plugins": {
    "triggers": [
      {
        "type": "plugin-trigger",
        "title": "Plugin Trigger",
        "description": "Description",
        "icon": "puzzle-piece",
        "isPlugin": true,
        "pluginName": "plugin-name"
      }
    ],
    "actions": [],
    "utilities": [],
    "widgets": [],
    "controls": [],
    "custom": []
  },
  "totalCount": 1
}

Execute Tool

POST /:toolName/execute

  • Authentication: Required
  • Parameters:
    • toolName (path): Tool identifier — accepts kebab-case (chucknorris-get-joke) or snake_case (chucknorris_get_joke). Resolves across native orchestrator tools, agent/workflow/goal/code/widget/tool-forge tools, registry tools, and installed plugin tools.
  • Body:
{
  "args": { "category": "dev" }
}
  • Description: Universal tool execution endpoint. Invokes any registered tool by name with the supplied arguments and returns the parsed result. Argument validation, OAuth resolution for tools that require it, and registry/plugin dispatch are all handled internally — this is the same pipeline the chat orchestrator uses to call tools.
  • Response (success):
{
  "success": true,
  "tool": "chucknorris-get-joke",
  "result": {
    "joke": "Chuck Norris doesn't write code...",
    "id": "abc123",
    "categories": ["dev"],
    "url": "https://api.chucknorris.io/jokes/abc123"
  }
}
  • Response (tool reported failure):
{
  "success": false,
  "tool": "chucknorris-get-joke",
  "error": "Validation failed: 'category' must be one of [...]",
  "details": { "...": "full payload returned by the tool" }
}
  • Response 401: { "success": false, "error": "Authentication required" }

Custom Tool Routes

Base path: /api/custom-tools

Health Check

GET /health

  • Authentication: None
  • Description: Check if the custom tool service is running
  • Response:
{
  "status": "OK"
}

Get All Custom Tools

GET /

  • Authentication: Required
  • Description: Retrieve all custom tools for the authenticated user
  • Response:
[
  {
    "id": "tool-id",
    "name": "Custom Tool",
    "description": "Tool description",
    "config": {},
    "userId": "user-id",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
]

Save/Update Custom Tool

POST /save

  • Authentication: Required
  • Description: Create a new custom tool or update an existing one
  • Body:
{
  "id": "optional-tool-id",
  "name": "Custom Tool",
  "description": "Tool description",
  "config": {}
}
  • Response:
{
  "success": true,
  "tool": {
    "id": "tool-id",
    "name": "Custom Tool",
    "description": "Tool description",
    "config": {},
    "userId": "user-id",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

Get Custom Tool by ID

GET /:id

  • Authentication: Required
  • Parameters:
    • id (path): Tool ID
  • Description: Retrieve a specific custom tool by ID
  • Response:
{
  "id": "tool-id",
  "name": "Custom Tool",
  "description": "Tool description",
  "config": {},
  "userId": "user-id",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Update Custom Tool

PUT /:id

  • Authentication: Required
  • Parameters:
    • id (path): Tool ID
  • Body:
{
  "name": "Updated Tool Name",
  "description": "Updated description",
  "config": {}
}
  • Response:
{
  "success": true,
  "tool": {
    "id": "tool-id",
    "name": "Updated Tool Name",
    "description": "Updated description",
    "config": {},
    "userId": "user-id",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

Delete Custom Tool

DELETE /:id

  • Authentication: Required
  • Parameters:
    • id (path): Tool ID
  • Description: Delete a custom tool by ID
  • Response:
{
  "success": true,
  "message": "Custom tool deleted successfully"
}

Tool Schema Routes

Base path: /api/tool-schemas

Get All Tool Schemas

GET /schemas

  • Authentication: None
  • Description: Get all tool schemas organized by category
  • Response:
{
  "triggers": [
    {
      "type": "trigger-type",
      "title": "Trigger Title",
      "description": "Trigger description",
      "schema": {}
    }
  ],
  "actions": [
    {
      "type": "action-type",
      "title": "Action Title",
      "description": "Action description",
      "schema": {}
    }
  ],
  "utilities": [
    {
      "type": "utility-type",
      "title": "Utility Title",
      "description": "Utility description",
      "schema": {}
    }
  ]
}

Get Tool Schema by Type

GET /schemas/:toolType

  • Authentication: None
  • Parameters:
    • toolType (path): Tool type
  • Description: Get schema for a specific tool
  • Response:
{
  "type": "tool-type",
  "title": "Tool Title",
  "description": "Tool description",
  "schema": {
    "properties": {},
    "required": []
  }
}

Get Schemas by Category

GET /schemas/category/:category

  • Authentication: None
  • Parameters:
    • category (path): Category name (triggers, actions, utilities, etc.)
  • Description: Get schemas by category
  • Response:
[
  {
    "type": "tool-type",
    "title": "Tool Title",
    "description": "Tool description",
    "schema": {}
  }
]

Get Registry Statistics

GET /stats

  • Authentication: None
  • Description: Get registry statistics
  • Response:
{
  "totalTools": 50,
  "categories": {
    "triggers": 10,
    "actions": 25,
    "utilities": 15
  },
  "lastUpdated": "2024-01-01T00:00:00Z"
}

Get Tool Metadata

GET /metadata/:toolType

  • Authentication: None
  • Parameters:
    • toolType (path): Tool type
  • Description: Get metadata for a specific tool (includes source info)
  • Response:
{
  "type": "tool-type",
  "source": "builtin|plugin|custom",
  "plugin": "plugin-name",
  "version": "1.0.0",
  "author": "Author Name",
  "createdAt": "2024-01-01T00:00:00Z"
}

Reload Registry

POST /reload

  • Authentication: Required
  • Description: Reload the registry (useful for development)
  • Response:
{
  "success": true,
  "message": "Tool registry reloaded successfully",
  "stats": {
    "totalTools": 50,
    "categories": {
      "triggers": 10,
      "actions": 25,
      "utilities": 15
    }
  }
}

NPM Routes

Base path: /api/npm

Search MCP Servers

GET /search

  • Authentication: Required
  • Parameters:
    • q (query): Search query
    • limit (query): Maximum results (optional)
  • Description: Search for MCP servers on NPM
  • Response:
{
  "success": true,
  "packages": [
    {
      "name": "package-name",
      "version": "1.0.0",
      "description": "Package description",
      "author": "Author Name",
      "keywords": ["mcp", "server"],
      "downloads": 1000
    }
  ]
}

GET /popular

  • Authentication: Required
  • Description: Get popular MCP servers from NPM
  • Response:
{
  "success": true,
  "packages": [
    {
      "name": "popular-package",
      "version": "1.0.0",
      "description": "Popular package description",
      "downloads": 10000,
      "rating": 4.5
    }
  ]
}

Get Package Details

GET /package/:packageName

  • Authentication: Required
  • Parameters:
    • packageName (path): NPM package name
  • Description: Get detailed information about a specific NPM package
  • Response:
{
  "success": true,
  "package": {
    "name": "package-name",
    "version": "1.0.0",
    "description": "Package description",
    "author": "Author Name",
    "license": "MIT",
    "repository": "https://github.com/user/repo",
    "dependencies": {},
    "downloads": {
      "lastWeek": 1000,
      "lastMonth": 5000,
      "total": 50000
    },
    "readme": "README content"
  }
}

Test Package

POST /test

  • Authentication: Required
  • Body:
{
  "packageName": "package-name",
  "version": "1.0.0"
}
  • Response:
{
  "success": true,
  "testResults": {
    "compatible": true,
    "issues": [],
    "recommendations": []
  }
}
← Back
All documentation
Improve this page
Edit on GitHub