Tools API

LVNG ships 22 self-contained tools across 7 categories. The ToolRegistry auto-discovers tools at startup. Each tool exposes a name, description, category, JSON input schema, and an execute handler. Progressive discovery via the tool_search meta-tool lets agents find tools at runtime without loading all definitions upfront.

Base path: /api/v2/tools

Discovery

GET/api/v2/toolsAuthenticated

List all available tools. Filter by category or choose between full and deferred schema mode.

Query Parameters

categorystring

Filter by category: web, email, ai, apps, data, agent, meta.

modestring

full (default) returns inputSchema. deferred returns lightweight stubs.

Request

cURL

curl -X GET "https://api.lvng.ai/api/v2/tools?category=web" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "tools": [
    {
      "name": "web_search",
      "description": "Search the web and return relevant results.",
      "category": "web",
      "isReadOnly": true,
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "max_results": { "type": "integer", "default": 5 }
        },
        "required": ["query"]
      }
    }
  ],
  "total": 3
}

GET/api/v2/tools/:nameAuthenticated

Get full details for a specific tool including its schema and prompt helper.

Path Parameters

namestringrequired

Tool name (e.g. web_search, send_email).

Request

cURL

curl -X GET https://api.lvng.ai/api/v2/tools/send_email \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "tool": {
    "name": "send_email",
    "description": "Send an email from a connected account.",
    "category": "email",
    "isReadOnly": false,
    "inputSchema": {
      "type": "object",
      "properties": {
        "to": { "type": "string" },
        "subject": { "type": "string" },
        "body": { "type": "string" }
      },
      "required": ["to", "subject", "body"]
    }
  }
}

Execution

POST/api/v2/tools/:name/executeAuthenticated

Execute a tool with the provided input. Input is validated against the JSON schema before execution.

Path Parameters

namestringrequired

Name of the tool to execute.

Body Parameters

inputobjectrequired

Tool input matching the inputSchema.

contextobject

Execution context (userId, workspaceId).

Request

cURL

curl -X POST https://api.lvng.ai/api/v2/tools/web_search/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": { "query": "LVNG AI platform", "max_results": 3 }
  }'

Response 200

{
  "success": true,
  "result": [
    {
      "title": "LVNG - Autonomous AI Agents",
      "url": "https://lvng.ai",
      "snippet": "Multi-agent AI platform for workflow execution."
    }
  ],
  "tool": "web_search",
  "executionTime": 842
}

Progressive Discovery

GET/api/v2/tools/searchAuthenticated

Search tools by keyword. Returns full schemas for matched tools ranked by relevance.

Query Parameters

qstringrequired

Search query matched against name, description, and category.

max_resultsnumber

Maximum tools to return (default 5).

Request

cURL

curl -X GET "https://api.lvng.ai/api/v2/tools/search?q=email" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "query": "email",
  "tools": [
    { "name": "send_email", "description": "Send an email.", "category": "email" },
    { "name": "read_emails", "description": "Read emails from inbox.", "category": "email" },
    { "name": "search_emails", "description": "Search emails by query.", "category": "email" }
  ],
  "total": 3
}

Permissions

GET/api/v2/tools/permissionsAuthenticated

Get the current tool permission configuration for the workspace.

Request

cURL

curl -X GET https://api.lvng.ai/api/v2/tools/permissions \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "permissions": {
    "mode": "gated",
    "rules": [
      { "category": "web", "allow": true },
      { "category": "email", "allow": false }
    ],
    "audit_log": true
  }
}

PUT/api/v2/tools/permissionsAuthenticated

Update tool permission configuration. Requires workspace admin.

Body Parameters

modestringrequired

Permission mode: open, gated, plan, or audit.

rulesarray

Array of allow/deny rules by category or tool name.

audit_logboolean

Enable audit logging for all tool executions.

Request

cURL

curl -X PUT https://api.lvng.ai/api/v2/tools/permissions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "gated",
    "rules": [{ "category": "web", "allow": true }],
    "audit_log": true
  }'

Response 200

{
  "success": true,
  "permissions": {
    "mode": "gated",
    "rules": [{ "category": "web", "allow": true }],
    "audit_log": true,
    "updated_at": "2026-04-01T12:00:00.000Z"
  }
}