Tools API

The Tools API allows you to search, discover, and execute TPMJS tools programmatically.

List Tools

GET /api/tools

Retrieve a paginated list of tools with optional filtering.

Query Parameters

  • limit - Number of results (default: 20, max: 50)
  • offset - Pagination offset
  • category - Filter by category
  • q - Search query

Example Request

curl "https://tpmjs.com/api/tools?category=communication&limit=10"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "clx123abc",
      "name": "discordPostTool",
      "description": "Post messages to Discord channels",
      "qualityScore": 0.85,
      "package": {
        "npmPackageName": "@tpmjs/discord-post",
        "category": "communication"
      }
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

Get Tool

GET /api/tools/:id

Retrieve detailed information about a specific tool.

Path Parameters

  • id - Tool ID or package/tool slug

Example Request

curl "https://tpmjs.com/api/tools/@tpmjs/discord-post/discordPostTool"

Execute Tool

POST /api/tools/execute/:slug

Execute a tool with an AI agent. Returns streaming SSE response.

Request Body

{
  "prompt": "Send a hello message to #general channel",
  "parameters": {
    "channel": "#general"
  }
}

TypeScript Example

import { executeToolCall } from '@tpmjs/registry-execute';

const result = await executeToolCall({
  toolId: '@tpmjs/discord-post/discordPostTool',
  prompt: 'Send hello to #general',
  apiKey: 'your-api-key',
  onChunk: (text) => console.log(text),
});

console.log(result.output);

Trending Tools

GET /api/tools/trending

Get trending tools based on downloads, ratings, and activity.

Query Parameters

  • period - Time period: day, week, month, all (default: week)
  • category - Filter by category
  • limit - Number of results (default: 20)

Example Request

curl "https://tpmjs.com/api/tools/trending?period=week&limit=10"

Rate Tool

POST /api/tools/:id/rate

Rate a tool from 1-5 stars. Requires authentication.

Request Body

{
  "rating": 5
}

Example Response

{
  "success": true,
  "data": {
    "userRating": 5,
    "averageRating": 4.5,
    "ratingCount": 42
  }
}