New VDF AI Enterprise is now available on AWS Marketplace
API Reference

Tools

Tools are the capabilities agents can call — web search, document parsing, chart generation, integrations, and more. The catalogue combines the platform's built-in tools with any custom HTTP tools and connected tool servers your deployment adds.

You can list the tools available to you, run a tool directly, and define your own HTTP tools: a tool is described once — its endpoint, method, and input schema — and thereafter any agent can call it. HTTP tools are private to the user who creates them until shared.

What you see and can run is scoped to you: built-in tools are available to everyone, while custom HTTP tools and tools from connected servers are limited to those you own or that have been shared with you.

Endpoints 6

Paths are relative to /agent-hub-api

List tools

GET /agent-hub-api/api/tools

Also available as GET /agent-hub-api/api/tool-registry

Returns the tools available to the caller.

Returns every tool the caller can use, each with its input schema and, where applicable, the domain it is filed under. The list combines built-in tools with the custom HTTP tools and connected-server tools visible to you.

Authentication
Bearer token How it works

Parameters

No parameters.

Returns

Returns a list of tool descriptors under tools.

Errors

  • 503 The tool service was unavailable.
Request 
curl "$VDF_BASE_URL/agent-hub-api/api/tools" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "tools": [
    {
      "name": "web_search",
      "description": "Search the web for information.",
      "parameters_schema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          }
        },
        "required": [
          "query"
        ]
      },
      "type": "mcp",
      "mcp_category": "web"
    },
    {
      "name": "crm_lookup",
      "description": "Look up a customer record in the CRM.",
      "parameters_schema": {
        "type": "object",
        "properties": {
          "account_id": {
            "type": "string"
          }
        },
        "required": [
          "account_id"
        ]
      },
      "type": "http",
      "endpoint_url": "https://tools.example.com/crm/lookup",
      "http_method": "POST",
      "auth_method": "bearer_passthrough",
      "owner_user_id": 42
    }
  ]
}

Run a tool

POST /agent-hub-api/api/tools/execute

Runs a single tool with the given parameters.

Runs one tool directly, outside of an agent, and returns its result. You may run any tool available to you — built-in tools, and the custom HTTP or connected-server tools you own or that were shared with you; naming a tool you cannot use is rejected as if it did not exist.

Authentication
Bearer token How it works

Body parameters application/json

  • tool_name string Required

    The tool to run.

  • parameters object

    Arguments for the tool, matching its input schema.

Returns

Returns the tool's output under result.

Errors

  • 400 tool_name is missing, or parameters is not an object.
  • 422 The tool ran but reported an execution error, such as invalid arguments.
  • 503 The tool service was unavailable.
  • 500 The tool could not be run.
Request 
curl -X POST "$VDF_BASE_URL/agent-hub-api/api/tools/execute" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "web_search",
    "parameters": {
      "query": "VDF AI on-prem release notes"
    }
  }'
Response 200 
{
  "success": true,
  "result": {
    "text": "Top results for the query...",
    "items": []
  }
}

Create an HTTP tool

POST /agent-hub-api/api/tools/http

Defines a custom HTTP tool that you own.

Registers one of your own HTTP endpoints as a tool that agents can call. endpoint_url must be a publicly resolvable http/https URL; URLs that resolve to private, loopback, or link-local addresses are rejected. Set auth_method to bearer_passthrough to forward the caller's access token to your endpoint — this is allowed only for hosts your administrator has allowlisted — or to none to send no credentials. The tool name must be unique across the catalogue and match ^[a-zA-Z0-9_-]+$.

Authentication
Bearer token How it works

Body parameters application/json

  • tool_name string Required

    Unique tool name, matching ^[a-zA-Z0-9_-]+$. name is accepted as an alias.

  • endpoint_url string Required

    The http/https endpoint to call. Must resolve to a public address.

  • http_method string

    HTTP method used to call the endpoint.

    Defaults to POST.

    Possible values
    • GET
    • POST
  • auth_method string

    How the endpoint is authenticated. bearer_passthrough forwards the caller's access token and requires an allowlisted host.

    Defaults to bearer_passthrough.

    Possible values
    • bearer_passthrough
    • none
  • description string

    What the tool does; shown to agents.

  • parameters_schema object

    JSON Schema for the tool's inputs. Must be an object schema.

  • mcp_category string

    Catalogue category. category is accepted as an alias.

    Defaults to core.

  • default_domain_id string

    Domain to file the tool under by default.

Returns

Returns the created tool descriptor under tool.

Errors

  • 400 Validation failed: a required field is missing, the name is invalid or already taken, or the endpoint URL is not allowed.
Request 
curl -X POST "$VDF_BASE_URL/agent-hub-api/api/tools/http" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "crm_lookup",
    "description": "Look up a customer record in the CRM.",
    "endpoint_url": "https://tools.example.com/crm/lookup",
    "http_method": "POST",
    "auth_method": "bearer_passthrough",
    "parameters_schema": {
      "type": "object",
      "properties": {
        "account_id": {
          "type": "string"
        }
      },
      "required": [
        "account_id"
      ]
    }
  }'
Response 201 
{
  "success": true,
  "tool": {
    "name": "crm_lookup",
    "description": "Look up a customer record in the CRM.",
    "parameters_schema": {
      "type": "object",
      "properties": {
        "account_id": {
          "type": "string"
        }
      },
      "required": [
        "account_id"
      ]
    },
    "parameters": {
      "account_id": {
        "type": "string"
      }
    },
    "category": "core",
    "type": "http",
    "endpoint_url": "https://tools.example.com/crm/lookup",
    "http_method": "POST",
    "auth_method": "bearer_passthrough",
    "owner_user_id": 42,
    "is_active": true
  }
}

Retrieve an HTTP tool

GET /agent-hub-api/api/tools/http/{tool_name}

Retrieves a custom HTTP tool you own, for editing.

Returns the definition of one of your HTTP tools, including its endpoint, method, authentication mode, and input schema. Only the owner can retrieve a tool this way.

Authentication
Bearer token How it works

Path parameters

  • tool_name string Required

    The tool name.

Returns

Returns the tool descriptor under tool.

Errors

  • 404 No HTTP tool with this name is owned by the caller.
Request 
curl "$VDF_BASE_URL/agent-hub-api/api/tools/http/crm_lookup" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "tool": {
    "name": "crm_lookup",
    "description": "Look up a customer record in the CRM.",
    "parameters_schema": {
      "type": "object",
      "properties": {
        "account_id": {
          "type": "string"
        }
      },
      "required": [
        "account_id"
      ]
    },
    "parameters": {
      "account_id": {
        "type": "string"
      }
    },
    "category": "core",
    "type": "http",
    "endpoint_url": "https://tools.example.com/crm/lookup",
    "http_method": "POST",
    "auth_method": "bearer_passthrough",
    "owner_user_id": 42,
    "is_active": true
  }
}

Update an HTTP tool

PUT /agent-hub-api/api/tools/http/{tool_name}

Updates a custom HTTP tool you own.

Applies a partial update to one of your HTTP tools. The endpoint URL is re-validated whenever it or the authentication mode changes, under the same rules as Create an HTTP tool. Only the owner can update a tool.

Authentication
Bearer token How it works

Path parameters

  • tool_name string Required

    The tool name.

Body parameters application/json

  • description string

    What the tool does.

  • endpoint_url string

    The http/https endpoint to call. Must resolve to a public address.

  • http_method string

    HTTP method used to call the endpoint.

    Possible values
    • GET
    • POST
  • auth_method string

    How the endpoint is authenticated.

    Possible values
    • bearer_passthrough
    • none
  • parameters_schema object

    JSON Schema for the tool's inputs.

  • mcp_category string

    Catalogue category. category is accepted as an alias.

  • default_domain_id string

    Domain to file the tool under by default.

Returns

Returns the updated tool descriptor under tool.

Errors

  • 400 Validation failed, such as an endpoint URL that is not allowed.
  • 404 No HTTP tool with this name is owned by the caller.
Request 
curl -X PUT "$VDF_BASE_URL/agent-hub-api/api/tools/http/crm_lookup" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Look up a customer or prospect record in the CRM."
  }'
Response 200 
{
  "success": true,
  "tool": {
    "name": "crm_lookup",
    "description": "Look up a customer or prospect record in the CRM.",
    "parameters_schema": {
      "type": "object",
      "properties": {
        "account_id": {
          "type": "string"
        }
      },
      "required": [
        "account_id"
      ]
    },
    "category": "core",
    "type": "http",
    "endpoint_url": "https://tools.example.com/crm/lookup",
    "http_method": "POST",
    "auth_method": "bearer_passthrough",
    "owner_user_id": 42,
    "is_active": true
  }
}

Delete an HTTP tool

DEL /agent-hub-api/api/tools/http/{tool_name}

Deactivates a custom HTTP tool you own.

Deactivates one of your HTTP tools so it can no longer be listed or called. Only the owner can delete a tool.

Authentication
Bearer token How it works

Path parameters

  • tool_name string Required

    The tool name.

Returns

Returns success: true once the tool is deactivated.

Errors

  • 404 No HTTP tool with this name is owned by the caller.
Request 
curl -X DELETE "$VDF_BASE_URL/agent-hub-api/api/tools/http/crm_lookup" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true
}