Tools API

List Tools

GET /api/v1/tools

Returns all enabled tools from approved plugins with their JSON Schema definitions. Tools from plugins that are still in draft, pending_review, declined, or revision_requested status are excluded.

Authentication

API key required: Authorization: Bearer nk_live_...

Query Parameters

Example (manual): GET /api/v1/tools?plugin=gmail,stripe

Example (MCP with realtime): GET /api/v1/tools?plugin=notion&userId=user_123

Response

Each tool includes a source field indicating whether it was defined manually or discovered from an MCP server:

{
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "slug": "GMAIL_SEND_EMAIL",
      "name": "Send Email",
      "description": "Send an email via Gmail API",
      "method": "POST",
      "path": "/gmail/v1/users/me/messages/send",
      "inputSchema": {
        "type": "object",
        "properties": {
          "to": { "type": "string" },
          "subject": { "type": "string" },
          "body": { "type": "string" }
        },
        "required": ["to", "subject", "body"]
      },
      "outputSchema": null,
      "pluginSlug": "gmail",
      "pluginName": "Gmail",
      "source": "manual"
    },
    {
      "id": "mcp-notion-search",
      "slug": "NOTION_SEARCH",
      "name": "notion-search",
      "description": "Search across a Notion workspace",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" }
        },
        "required": ["query"]
      },
      "pluginSlug": "notion",
      "pluginName": "Notion",
      "source": "mcp"
    }
  ]
}

Execute Tool

POST /api/v1/tools/execute

Execute a tool for a specific end-user. The runtime proxy resolves the tool, decrypts the user's credentials, injects auth headers, calls the external API, and returns the result.

Authentication

API key required: Authorization: Bearer nk_live_...

Request Body

{
  "userId": "user_123",
  "tool": "GMAIL_SEND_EMAIL",
  "params": {
    "to": "hello@example.com",
    "subject": "Hello",
    "body": "Sent by an AI agent"
  }
}

Response (Success — 200)

{
  "success": true,
  "data": { "messageId": "abc123" },
  "status": 200,
  "latencyMs": 342
}

Response (Error — 502)

{
  "success": false,
  "error": "Upstream API returned 403 Forbidden",
  "status": 502,
  "latencyMs": 1205
}

Response Fields

Execution Details

The proxy performs these steps:

For manual tools:

1. Resolves the tool by slug (only from approved plugins)
2. Fetches the plugin's baseUrl
3. Finds the user's connected account for this plugin
4. Decrypts credentials (AES-256-GCM)
5. Injects auth headers based on auth method type
6. Interpolates {placeholder} path params from params
7. Sends remaining params as JSON body (for non-GET)
8. Returns the response and logs the execution

For MCP tools:

1. Resolves the tool by slug from mcpToolCache (only from approved plugins)
2. Finds the user's MCP connection for the plugin
3. Decrypts the MCP access token (auto-refreshes if expired)
4. Connects to the MCP server using the Streamable HTTP transport
5. Calls the tool via the MCP protocol (tools/call)
6. Returns the result and logs the execution

MCP Tool Discovery Behavior

When userId is provided and the plugin has MCP configured: