API

v1.0

TPMJS API Reference

REST API and MCP protocol for accessing tools, collections, and agents.

Base URL: https://tpmjs.com/api

Overview

The TPMJS API provides programmatic access to the tool registry, collections, and agents. There are two ways to interact with the API:

REST API

Standard REST endpoints for listing tools, searching, and executing. No authentication required for public endpoints.

MCP Protocol

JSON-RPC 2.0 over HTTP for AI clients like Claude Desktop, Cursor, and others that support Model Context Protocol.

Quick Start

Try these examples to get started. All API endpoints require authentication via API key. Generate one from Settings → TPMJS API Keys in your dashboard.

1. List Tools

curl "https://tpmjs.com/api/tools?limit=5" \
  -H "Authorization: Bearer tpmjs_sk_your_api_key_here" | jq

2. Search Tools

curl "https://tpmjs.com/api/tools/search?q=web+scraping&limit=3" \
  -H "Authorization: Bearer tpmjs_sk_your_api_key_here" | jq

3. Get Tool Details

curl "https://tpmjs.com/api/tools/@tpmjs/hello/helloWorldTool" \
  -H "Authorization: Bearer tpmjs_sk_your_api_key_here" | jq

4. MCP Tools List (Collection)

curl -X POST "https://tpmjs.com/api/mcp/ajax/ajax-collection-tbc/http" \
  -H "Authorization: Bearer tpmjs_sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' | jq

Authentication

All API endpoints require authentication via TPMJS API keys. Generate an API key from your dashboard at Settings → TPMJS API Keys.

API Key Format

API keys use the tpmjs_sk_ prefix and are passed in the Authorization header:

curl "https://tpmjs.com/api/tools" \
  -H "Authorization: Bearer tpmjs_sk_your_api_key_here"

API Key Scopes

mcp:execute - MCP tool execution
agent:chat - Agent conversations
bridge:connect - Bridge connections
collection:read - Collection access
usage:read - Usage analytics

Rate Limits

FREE tier: 100 requests/hour
PRO tier: 1,000 requests/hour
ENTERPRISE tier: 10,000 requests/hour

Tools

GET/api/tools

List all tools with optional filtering and pagination.

Parameter	Type	Required	Description
q	string	No	Search query
category	string	No	Filter by category
official	boolean	No	Official tools only
limit	number	No	Results per page (default: 20, max: 50)
offset	number	No	Pagination offset

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

GET/api/tools/[package]/[toolName]

Get detailed information about a specific tool.

curl "https://tpmjs.com/api/tools/@tpmjs/hello/helloWorldTool"

Response

{
  "success": true,
  "data": {
    "id": "clx...",
    "name": "helloWorldTool",
    "description": "Returns a simple greeting",
    "package": {
      "npmPackageName": "@tpmjs/hello",
      "npmVersion": "1.0.0"
    },
    "inputSchema": {
      "type": "object",
      "properties": {}
    },
    "healthStatus": "HEALTHY",
    "qualityScore": 0.85
  }
}

Search

GET/api/tools/search

BM25-ranked semantic search optimized for AI tool discovery.

Parameter	Type	Required	Description
q	string	Yes	Search query
limit	number	No	Max results (default: 5, max: 20)

curl "https://tpmjs.com/api/tools/search?q=convert+pdf+to+markdown&limit=5"

Collections

GET/api/public/collections

List all public collections with tools and creator info.

curl "https://tpmjs.com/api/public/collections"

GET/api/public/collections/[id]

Get a specific public collection with its tools.

curl "https://tpmjs.com/api/public/collections/clx123..."

GET/api/public/users/[username]/collections/[slug]

Get a collection by username and slug (human-readable URL).

curl "https://tpmjs.com/api/public/users/ajax/collections/web-tools"

Agents

GET/api/public/agents

List all public agents with their configurations.

curl "https://tpmjs.com/api/public/agents"

GET/api/public/users/[username]/agents/[uid]

Get an agent by username and unique identifier.

curl "https://tpmjs.com/api/public/users/lisa/agents/alpha"

Stats

GET/api/stats

Get platform-wide statistics including tool counts and categories.

curl "https://tpmjs.com/api/stats"

Response

{
  "success": true,
  "data": {
    "totalTools": 150,
    "totalPackages": 45,
    "totalExecutions": 12500,
    "categories": {
      "web-scraping": 25,
      "text-analysis": 18,
      "code-generation": 15
    }
  }
}

MCP Overview

TPMJS implements the Model Context Protocol (MCP) for AI clients. Each public collection exposes an MCP endpoint that can be connected to Claude Desktop, Cursor, or any MCP-compatible client.

Endpoint Format

POST https://tpmjs.com/api/mcp/[username]/[collection-slug]/http

Request Headers

Authorization: Bearer tpmjs_sk_your_api_key_hereContent-Type: application/json

Protocol

JSON-RPC 2.0 with MCP methods: initialize, tools/list, tools/call

MCP Initialize

POST/api/mcp/[username]/[slug]/http

Initialize an MCP session and get server capabilities.

Request

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "id": 1
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "serverInfo": {
      "name": "TPMJS: My Collection",
      "version": "1.0.0"
    },
    "capabilities": {
      "tools": {}
    }
  }
}

MCP Tools List

POST/api/mcp/[username]/[slug]/http

List all tools available in the collection with their schemas.

Request

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 2
}

Response

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "tpmjs-tools-toc-generate--tocGenerateTool",
        "description": "Generate a table of contents from markdown",
        "inputSchema": {
          "type": "object",
          "required": ["markdown"],
          "properties": {
            "markdown": { "type": "string" }
          }
        }
      }
    ]
  }
}

MCP Tools Call

POST/api/mcp/[username]/[slug]/http

Execute a tool from the collection with the provided arguments.

Request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "tpmjs-tools-toc-generate--tocGenerateTool",
    "arguments": {
      "markdown": "# Heading 1\n## Heading 2\n### Heading 3"
    }
  },
  "id": 3
}

Response

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"toc\": \"- [Heading 1](#heading-1)\\n  - [Heading 2](#heading-2)\"}"
      }
    ]
  }
}

Full cURL Example

curl -X POST "https://tpmjs.com/api/mcp/ajax/ajax-collection-tbc/http" \
  -H "Authorization: Bearer tpmjs_sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "tpmjs-tools-changelog-entry--changelogEntryTool",
      "arguments": {
        "version": "1.0.0",
        "changes": [
          {"type": "Added", "description": "New feature"}
        ]
      }
    },
    "id": 1
  }'

Execute Tool

POST/api/tools/execute/[package]/[toolName]

Execute a tool with an AI agent and stream the response.

Parameter	Type	Required	Description
prompt	string	Yes	Natural language prompt (max 2000 chars)
parameters	object	No	Direct tool parameters

curl -X POST "https://tpmjs.com/api/tools/execute/@tpmjs/hello/helloWorldTool" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Say hello to the world"}'

Streaming Responses

The execute endpoint returns Server-Sent Events (SSE) for real-time streaming.

event: chunk

Streaming text from the AI agent

event: tokens

Token usage updates

event: complete

Final result with output and timing

event: error

Error if execution fails

JavaScript Example

const response = await fetch(
  'https://tpmjs.com/api/tools/execute/@tpmjs/hello/helloWorldTool',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer tpmjs_sk_your_api_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ prompt: 'Say hello' }),
  }
);

const reader = response.body?.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  for (const line of chunk.split('\n')) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      console.log(data);
    }
  }
}

Success Response

All API endpoints return a consistent JSON response format.

{
  "success": true,
  "data": { ... },
  "pagination": {
    "limit": 20,
    "offset": 0,
    "hasMore": true
  },
  "meta": {
    "version": "1.0.0",
    "timestamp": "2026-01-10T12:00:00.000Z",
    "requestId": "abc123..."
  }
}

Error Handling

Errors include a code and message for debugging.

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Tool not found"
  },
  "meta": {
    "version": "1.0.0",
    "timestamp": "2026-01-10T12:00:00.000Z"
  }
}

HTTP Status Codes

200

Success

400

Bad request / validation error

401

Authentication required

404

Resource not found

429

Rate limit exceeded

500

Internal server error

Pagination

List endpoints support limit/offset pagination.

Parameter	Type	Required	Description
limit	number	No	Items per page (default varies by endpoint)
offset	number	No	Number of items to skip

# Page 1: First 20 items
curl "https://tpmjs.com/api/tools?limit=20&offset=0"

# Page 2: Next 20 items
curl "https://tpmjs.com/api/tools?limit=20&offset=20"

Need More Help?

Check out the full documentation or try the interactive playground.