AI Tools Catalog API

The AI Tools Catalog API provides endpoints for managing, discovering, and interacting with AI tools and MCP servers in the PadawanForge community catalog.

🔗 Base URL

https://padawanforge.com/api/catalog

🔐 Authentication

All endpoints require authentication via session cookie or API key:

Cookie: session=your_session_token

Or:

Authorization: Bearer your_api_key

📋 Endpoints Overview

Method	Endpoint	Description
GET	`/tools`	List tools with filtering and sorting
POST	`/tools`	Create a new tool
GET	`/tools/:id`	Get specific tool details
PUT	`/tools/:id`	Update tool information
DELETE	`/tools/:id`	Delete tool (creator only)
POST	`/tools/:id/vote`	Vote on a tool
GET	`/tools/:id/reviews`	Get tool reviews
POST	`/tools/:id/reviews`	Add tool review
GET	`/categories`	Get available categories
GET	`/providers`	Get available providers
GET	`/collections`	Get user collections
POST	`/collections`	Create new collection
GET	`/collections/:id`	Get collection details
POST	`/collections/:id/items`	Add tool to collection

🛠️ Tools Endpoints

List Tools

Get a paginated list of tools with filtering and sorting options.

GET /api/catalog/tools

Query Parameters

Parameter	Type	Description	Default
`page`	integer	Page number (1-based)	1
`limit`	integer	Items per page (max 100)	20
`search`	string	Search query	-
`category`	string	Filter by category	-
`provider`	string	Filter by provider	-
`sort`	string	Sort order	`popularity`
`min_rating`	number	Minimum rating (0-5)	-
`is_featured`	boolean	Show only featured tools	-
`is_verified`	boolean	Show only verified tools	-
`tags`	string[]	Filter by tags	-

Sort Options

popularity - Sort by vote count and rating
rating - Sort by average rating
newest - Sort by creation date
oldest - Sort by creation date (ascending)
downloads - Sort by download count
name - Sort alphabetically

Example Request

GET /api/catalog/tools?page=1&limit=10&category=text-processing&sort=rating&min_rating=4.0

Response

{
  "success": true,
  "data": {
    "tools": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Advanced Text Analyzer",
        "description": "AI-powered text analysis with sentiment detection",
        "category": "text-processing",
        "provider": "openai",
        "version": "1.0.0",
        "is_public": true,
        "creator": {
          "id": "456e7890-e89b-12d3-a456-426614174001",
          "username": "johndoe",
          "avatar_url": "https://example.com/avatar.jpg"
        },
        "created_at": "2025-01-15T10:30:00Z",
        "updated_at": "2025-01-15T10:30:00Z",
        "download_count": 150,
        "rating": 4.5,
        "vote_count": 25,
        "tags": ["nlp", "sentiment", "analysis"],
        "screenshots": [
          "https://example.com/screenshot1.jpg",
          "https://example.com/screenshot2.jpg"
        ],
        "documentation_url": "https://example.com/docs",
        "repository_url": "https://github.com/example/tool",
        "license": "MIT",
        "is_featured": false,
        "is_verified": true,
        "user_vote": "up",
        "user_review": {
          "rating": 5,
          "review_text": "Excellent tool!"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 150,
      "pages": 15
    },
    "filters": {
      "categories": [
        {
          "name": "text-processing",
          "count": 45
        }
      ],
      "providers": [
        {
          "name": "openai",
          "count": 30
        }
      ]
    }
  }
}

Create Tool

Create a new tool in the catalog.

POST /api/catalog/tools

Request Body

{
  "name": "Advanced Text Analyzer",
  "description": "AI-powered text analysis with sentiment detection",
  "category": "text-processing",
  "provider": "openai",
  "version": "1.0.0",
  "is_public": true,
  "tags": ["nlp", "sentiment", "analysis"],
  "configuration": {
    "model": "gpt-4",
    "temperature": 0.7,
    "max_tokens": 1000,
    "system_prompt": "You are a text analysis expert..."
  },
  "screenshots": [
    "https://example.com/screenshot1.jpg"
  ],
  "documentation_url": "https://example.com/docs",
  "repository_url": "https://github.com/example/tool",
  "license": "MIT",
  "compatibility": {
    "min_version": "1.0.0",
    "max_version": "2.0.0",
    "platforms": ["web", "api"]
  }
}

Response

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Advanced Text Analyzer",
    "description": "AI-powered text analysis with sentiment detection",
    "category": "text-processing",
    "provider": "openai",
    "version": "1.0.0",
    "is_public": true,
    "creator_id": "456e7890-e89b-12d3-a456-426614174001",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z",
    "download_count": 0,
    "rating": 0.00,
    "vote_count": 0,
    "tags": ["nlp", "sentiment", "analysis"],
    "configuration": {
      "model": "gpt-4",
      "temperature": 0.7,
      "max_tokens": 1000,
      "system_prompt": "You are a text analysis expert..."
    },
    "screenshots": [
      "https://example.com/screenshot1.jpg"
    ],
    "documentation_url": "https://example.com/docs",
    "repository_url": "https://github.com/example/tool",
    "license": "MIT",
    "compatibility": {
      "min_version": "1.0.0",
      "max_version": "2.0.0",
      "platforms": ["web", "api"]
    },
    "is_featured": false,
    "is_verified": false
  }
}

Get Tool Details

Get detailed information about a specific tool.

GET /api/catalog/tools/:id

Response

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Advanced Text Analyzer",
    "description": "AI-powered text analysis with sentiment detection",
    "category": "text-processing",
    "provider": "openai",
    "version": "1.0.0",
    "is_public": true,
    "creator": {
      "id": "456e7890-e89b-12d3-a456-426614174001",
      "username": "johndoe",
      "avatar_url": "https://example.com/avatar.jpg"
    },
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z",
    "download_count": 150,
    "rating": 4.5,
    "vote_count": 25,
    "tags": ["nlp", "sentiment", "analysis"],
    "configuration": {
      "model": "gpt-4",
      "temperature": 0.7,
      "max_tokens": 1000,
      "system_prompt": "You are a text analysis expert..."
    },
    "screenshots": [
      "https://example.com/screenshot1.jpg",
      "https://example.com/screenshot2.jpg"
    ],
    "documentation_url": "https://example.com/docs",
    "repository_url": "https://github.com/example/tool",
    "license": "MIT",
    "compatibility": {
      "min_version": "1.0.0",
      "max_version": "2.0.0",
      "platforms": ["web", "api"]
    },
    "is_featured": false,
    "is_verified": true,
    "user_vote": "up",
    "user_review": {
      "id": "789e0123-e89b-12d3-a456-426614174002",
      "rating": 5,
      "review_text": "Excellent tool! Very easy to use.",
      "created_at": "2025-01-16T14:20:00Z"
    },
    "recent_reviews": [
      {
        "id": "789e0123-e89b-12d3-a456-426614174002",
        "user": {
          "username": "johndoe",
          "avatar_url": "https://example.com/avatar.jpg"
        },
        "rating": 5,
        "review_text": "Excellent tool! Very easy to use.",
        "created_at": "2025-01-16T14:20:00Z",
        "is_helpful_count": 3,
        "is_not_helpful_count": 0
      }
    ],
    "statistics": {
      "total_views": 500,
      "total_downloads": 150,
      "total_votes": 25,
      "up_votes": 23,
      "down_votes": 2,
      "total_reviews": 8,
      "average_rating": 4.5,
      "recent_usage": 12
    }
  }
}

Update Tool

Update an existing tool (creator only).

PUT /api/catalog/tools/:id

Request Body

{
  "name": "Advanced Text Analyzer v2",
  "description": "Updated AI-powered text analysis with enhanced sentiment detection",
  "version": "2.0.0",
  "is_public": true,
  "tags": ["nlp", "sentiment", "analysis", "enhanced"],
  "configuration": {
    "model": "gpt-4-turbo",
    "temperature": 0.5,
    "max_tokens": 2000,
    "system_prompt": "You are an advanced text analysis expert..."
  }
}

Response

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Advanced Text Analyzer v2",
    "description": "Updated AI-powered text analysis with enhanced sentiment detection",
    "version": "2.0.0",
    "updated_at": "2025-01-16T15:45:00Z",
    // ... other fields
  }
}

Delete Tool

Delete a tool (creator only).

DELETE /api/catalog/tools/:id

Response

{
  "success": true,
  "message": "Tool deleted successfully"
}

👍 Voting Endpoints

Vote on Tool

Vote up or down on a tool.

POST /api/catalog/tools/:id/vote

Request Body

{
  "vote_type": "up"
}

Response

{
  "success": true,
  "data": {
    "tool_id": "123e4567-e89b-12d3-a456-426614174000",
    "user_id": "456e7890-e89b-12d3-a456-426614174001",
    "vote_type": "up",
    "created_at": "2025-01-16T16:00:00Z"
  }
}

📝 Review Endpoints

Get Tool Reviews

Get reviews for a specific tool.

GET /api/catalog/tools/:id/reviews

Query Parameters

Parameter	Type	Description	Default
`page`	integer	Page number	1
`limit`	integer	Reviews per page	10
`sort`	string	Sort order (`newest`, `oldest`, `rating`)	`newest`

Response

{
  "success": true,
  "data": {
    "reviews": [
      {
        "id": "789e0123-e89b-12d3-a456-426614174002",
        "user": {
          "id": "456e7890-e89b-12d3-a456-426614174001",
          "username": "johndoe",
          "avatar_url": "https://example.com/avatar.jpg"
        },
        "rating": 5,
        "review_text": "Excellent tool! Very easy to use and produces accurate results.",
        "created_at": "2025-01-16T14:20:00Z",
        "updated_at": "2025-01-16T14:20:00Z",
        "is_verified": true,
        "is_helpful_count": 3,
        "is_not_helpful_count": 0
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 8,
      "pages": 1
    },
    "summary": {
      "average_rating": 4.5,
      "total_reviews": 8,
      "rating_distribution": {
        "5": 5,
        "4": 2,
        "3": 1,
        "2": 0,
        "1": 0
      }
    }
  }
}

Add Tool Review

Add a review for a tool.

POST /api/catalog/tools/:id/reviews

Request Body

{
  "rating": 5,
  "review_text": "Excellent tool! Very easy to use and produces accurate results."
}

Response

{
  "success": true,
  "data": {
    "id": "789e0123-e89b-12d3-a456-426614174002",
    "tool_id": "123e4567-e89b-12d3-a456-426614174000",
    "user_id": "456e7890-e89b-12d3-a456-426614174001",
    "rating": 5,
    "review_text": "Excellent tool! Very easy to use and produces accurate results.",
    "created_at": "2025-01-16T16:30:00Z",
    "updated_at": "2025-01-16T16:30:00Z",
    "is_verified": false,
    "is_helpful_count": 0,
    "is_not_helpful_count": 0
  }
}

📂 Categories & Providers

Get Categories

Get available tool categories.

GET /api/catalog/categories

Response

{
  "success": true,
  "data": [
    {
      "name": "text-processing",
      "description": "Text analysis, generation, and processing tools",
      "icon": "file-text",
      "color": "#3B82F6",
      "sort_order": 1,
      "is_active": true,
      "tool_count": 45
    },
    {
      "name": "image-processing",
      "description": "Image generation, editing, and analysis tools",
      "icon": "image",
      "color": "#10B981",
      "sort_order": 2,
      "is_active": true,
      "tool_count": 32
    }
  ]
}

Get Providers

Get available AI providers.

GET /api/catalog/providers

Response

{
  "success": true,
  "data": [
    {
      "name": "openai",
      "display_name": "OpenAI",
      "description": "OpenAI GPT models and API services",
      "website_url": "https://openai.com",
      "logo_url": "https://example.com/openai-logo.png",
      "is_active": true,
      "tool_count": 30
    },
    {
      "name": "anthropic",
      "display_name": "Anthropic",
      "description": "Claude AI models and services",
      "website_url": "https://anthropic.com",
      "logo_url": "https://example.com/anthropic-logo.png",
      "is_active": true,
      "tool_count": 25
    }
  ]
}

📚 Collections Endpoints

Get User Collections

Get collections created by the current user.

GET /api/catalog/collections

Response

{
  "success": true,
  "data": [
    {
      "id": "abc12345-e89b-12d3-a456-426614174000",
      "name": "My Favorite NLP Tools",
      "description": "A collection of my favorite natural language processing tools",
      "is_public": true,
      "creator_id": "456e7890-e89b-12d3-a456-426614174001",
      "created_at": "2025-01-15T12:00:00Z",
      "updated_at": "2025-01-15T12:00:00Z",
      "tool_count": 5,
      "view_count": 25
    }
  ]
}

Create Collection

Create a new tool collection.

POST /api/catalog/collections

Request Body

{
  "name": "My Favorite NLP Tools",
  "description": "A collection of my favorite natural language processing tools",
  "is_public": true
}

Response

{
  "success": true,
  "data": {
    "id": "abc12345-e89b-12d3-a456-426614174000",
    "name": "My Favorite NLP Tools",
    "description": "A collection of my favorite natural language processing tools",
    "is_public": true,
    "creator_id": "456e7890-e89b-12d3-a456-426614174001",
    "created_at": "2025-01-15T12:00:00Z",
    "updated_at": "2025-01-15T12:00:00Z",
    "tool_count": 0,
    "view_count": 0
  }
}

Get Collection Details

Get details of a specific collection.

GET /api/catalog/collections/:id

Response

{
  "success": true,
  "data": {
    "id": "abc12345-e89b-12d3-a456-426614174000",
    "name": "My Favorite NLP Tools",
    "description": "A collection of my favorite natural language processing tools",
    "is_public": true,
    "creator": {
      "id": "456e7890-e89b-12d3-a456-426614174001",
      "username": "johndoe",
      "avatar_url": "https://example.com/avatar.jpg"
    },
    "created_at": "2025-01-15T12:00:00Z",
    "updated_at": "2025-01-15T12:00:00Z",
    "tool_count": 5,
    "view_count": 25,
    "tools": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Advanced Text Analyzer",
        "description": "AI-powered text analysis with sentiment detection",
        "category": "text-processing",
        "provider": "openai",
        "rating": 4.5,
        "vote_count": 25,
        "added_at": "2025-01-15T12:30:00Z"
      }
    ]
  }
}

Add Tool to Collection

Add a tool to a collection.

POST /api/catalog/collections/:id/items

Request Body

{
  "tool_id": "123e4567-e89b-12d3-a456-426614174000"
}

Response

{
  "success": true,
  "data": {
    "id": "def67890-e89b-12d3-a456-426614174001",
    "collection_id": "abc12345-e89b-12d3-a456-426614174000",
    "tool_id": "123e4567-e89b-12d3-a456-426614174000",
    "added_at": "2025-01-15T12:30:00Z",
    "added_by": "456e7890-e89b-12d3-a456-426614174001"
  }
}

❌ Error Responses

All endpoints return consistent error responses:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "field": "name",
      "reason": "Name is required"
    }
  }
}

Error Codes

Code	Description
`VALIDATION_ERROR`	Invalid input data
`NOT_FOUND`	Resource not found
`UNAUTHORIZED`	Authentication required
`FORBIDDEN`	Insufficient permissions
`RATE_LIMITED`	Too many requests
`SERVER_ERROR`	Internal server error

🔒 Rate Limiting

API endpoints are rate-limited to prevent abuse:

General endpoints: 100 requests per hour
Voting endpoints: 10 requests per hour
Review endpoints: 5 requests per hour
Tool creation: 10 requests per hour

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

📊 Usage Analytics

The API automatically tracks usage for analytics:

Tool views: Tracked when tools are accessed
Downloads: Tracked when tools are downloaded
Votes: Tracked when users vote on tools
Reviews: Tracked when reviews are created
Search queries: Tracked for search optimization

This API provides a comprehensive interface for managing and interacting with the AI Tools Catalog, enabling rich community features and tool discovery.

← Authentication API Games API →