Collections API

The Collections API allows you to create and manage curated sets of tools for specific use cases.

List Collections

GET /api/collections

Retrieve a paginated list of public collections with optional filtering.

Query Parameters

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

Example Request

curl "https://tpmjs.com/api/collections?limit=10"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "clx123abc",
      "uid": "web-scraping-toolkit",
      "name": "Web Scraping Toolkit",
      "description": "Essential tools for web scraping and data extraction",
      "isPublic": true,
      "toolCount": 5,
      "likeCount": 42,
      "owner": {
        "id": "user123",
        "name": "John Doe",
        "username": "johndoe"
      }
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

Get Collection

GET /api/collections/:uid

Retrieve detailed information about a specific collection, including its tools.

Path Parameters

uid - Collection unique identifier or slug

Example Request

curl "https://tpmjs.com/api/collections/web-scraping-toolkit"

Example Response

{
  "success": true,
  "data": {
    "id": "clx123abc",
    "uid": "web-scraping-toolkit",
    "name": "Web Scraping Toolkit",
    "description": "Essential tools for web scraping and data extraction",
    "isPublic": true,
    "toolCount": 5,
    "likeCount": 42,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T14:45:00Z",
    "tools": [
      {
        "id": "tool123",
        "name": "webScraperTool",
        "description": "Scrape content from web pages"
      }
    ],
    "owner": {
      "id": "user123",
      "name": "John Doe",
      "username": "johndoe"
    }
  }
}

Create Collection

POST /api/collections

Create a new collection. Requires authentication.

Request Body

{
  "name": "My Data Tools",
  "uid": "my-data-tools",
  "description": "A collection of data processing tools",
  "isPublic": true
}

TypeScript Example

const response = await fetch('/api/collections', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    name: 'My Data Tools',
    uid: 'my-data-tools',
    description: 'A collection of data processing tools',
    isPublic: true
  })
});

const { data: collection } = await response.json();
console.log('Created collection:', collection.id);

Update Collection

PATCH /api/collections/:uid

Update an existing collection. Requires authentication and ownership.

Request Body

{
  "name": "Updated Collection Name",
  "description": "Updated description",
  "isPublic": false
}

Example Request

curl -X PATCH "https://tpmjs.com/api/collections/my-data-tools" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Collection Name"}'

Add Tool to Collection

POST /api/collections/:uid/tools

Add a tool to a collection. Requires authentication and ownership.

Request Body

{
  "toolId": "clx456def"
}

TypeScript Example

const response = await fetch('/api/collections/my-data-tools/tools', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    toolId: 'clx456def'
  })
});

if (response.ok) {
  console.log('Tool added to collection');
}

Remove Tool from Collection

DELETE /api/collections/:uid/tools/:toolId

Remove a tool from a collection. Requires authentication and ownership.

Example Request

curl -X DELETE "https://tpmjs.com/api/collections/my-data-tools/tools/clx456def" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "message": "Tool removed from collection"
}

Like Collection

POST /api/collections/:uid/like

Like or unlike a collection. Requires authentication.

TypeScript Example

// Like a collection
const response = await fetch('/api/collections/web-scraping-toolkit/like', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const { data } = await response.json();
console.log('Liked:', data.liked); // true if now liked, false if unliked

Delete Collection

DELETE /api/collections/:uid

Delete a collection. Requires authentication and ownership. This action cannot be undone.

Example Request

curl -X DELETE "https://tpmjs.com/api/collections/my-data-tools" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

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