Tools — AI Tools API

GET

List Tools

▶

GET /api/tools

Returns a paginated list of active AI tools with filtering, search, and sorting. Results are cached in KV for 60 seconds.

Query Parameters

Param	Type	Default	Description
page	number	1	Page number
limit	number	20	Results per page (max 200)
search	string	—	Search in name, description
toolType	string	—	e.g. `general`, `lawyer`, `video`, `real-estate`
pricingModel	enum	—	`free` \| `freemium` \| `paid` \| `enterprise`
featured	boolean	—	Filter featured tools only
targetIndustry	string	—	Industry slug e.g. `marketing`
tags	string	—	Comma-separated tags
sortBy	enum	rank	`rank` \| `createdAt` \| `rating` \| `viewCount` \| `reviewCount` \| `name` \| `startingPrice`
sortOrder	enum	desc	`asc` \| `desc`

Response

200 — Tool list

{
  "success": true,
  "data": {
    "tools": [
      {
        "id": "tool_abc",
        "slug": "my-ai-tool",
        "name": "My AI Tool",
        "singleLineDescription": "AI that does everything",
        "logoUrl": "https://example.com/logo.png",
        "toolType": "general",
        "targetIndustries": ["marketing", "healthcare"],
        "tags": ["ai", "automation"],
        "pricingModel": "freemium",
        "startingPrice": 19,
        "status": "active",
        "featured": false,
        "verified": true,
        "viewCount": 1250,
        "rating": 4.3,
        "reviewCount": 28,
        "rankScore": 312.5,
        "createdAt": "2026-02-01T00:00:00.000Z",
        "user": { "id": "usr_abc", "username": "johndoe", "avatar": "..." }
      }
    ],
    "pagination": { "total": 480, "page": 1, "limit": 20, "totalPages": 24 }
  }
}

GET

Homepage Listing

▶

GET /api/tools/homepage

Returns all four slot layers in a single response for the main site page. Each layer has its own ordering logic. Use the optional type param to scope all layers to a specific toolType — every sub-site (Lawyers, Videos, Real Estate) passes its own type so each gets an independent, cached listing. Results are cached in KV for 1 hour, keyed per type.

Query Parameters

Param	Type	Required	Description
type	string	optional	Scope all layers to this `toolType`. e.g. `lawyer`, `video`, `real-estate`. Omit for the general directory (all types).

Layers Returned

Key	Max	Order	Description
featured	12	rankScore DESC	Admin-curated tools (`featured = true`). Immediate KV purge when admin toggles.
promoted	5	—	Paid promoted tools. Always `[]` until the promotions table is added.
newAndRising	12	rankScore DESC	Published within the last 30 days, excluding featured. Each item includes `daysLive` and `recencyBonus` (+50→+30→+15→+5 weekly step-down).
ranked	24 (page 1)	rankScore DESC	All remaining active tools, excluding ids already in layers above. Use `meta.rankedTotal` for pagination.

Response

200 — Homepage layers

{
  "success": true,
  "data": {
    "featured": [
      {
        "id": "tool_abc", "slug": "harvey-ai", "name": "Harvey AI",
        "featured": true, "verified": true, "rankScore": 412.5
      }
    ],
    "promoted": [],
    "newAndRising": [
      {
        "id": "tool_xyz", "slug": "new-tool", "name": "New Tool",
        "publishedAt": "2026-04-23T00:00:00.000Z",
        "daysLive": 4,
        "recencyBonus": 50
      }
    ],
    "ranked": [
      { "id": "tool_def", "slug": "ranked-tool", "rankScore": 198.0 }
    ],
    "meta": {
      "type": "lawyer",
      "rankedTotal": 84,
      "rankedAt": "2026-04-27T06:00:00.000Z"
    }
  }
}

Sub-site Usage

Site	Request
General directory	`GET /api/tools/homepage`
AI for Lawyers	`GET /api/tools/homepage?type=lawyer`
AI for Videos	`GET /api/tools/homepage?type=video`
AI for Real Estate	`GET /api/tools/homepage?type=real-estate`

ℹ️ Each type value gets its own independent KV cache entry — type-scoped changes (e.g. a new lawyer tool published) do not invalidate the video or real-estate homepage caches. See Homepage Listing Strategy for the full slot-layer and cache design.

GET

Featured Tools

▶

GET /api/tools/featured

Returns top tools ranked by view count and plan tier (higher-paying creators rank higher within the same view tier). Cached for 5 minutes.

Query Parameters

Param	Type	Default	Description
limit	number	10	Number of tools to return (max 50)

Response

200 — Featured tools array

{ "success": true, "data": { "tools": [ /* tool objects */ ] } }

GET

Get Tool by Slug

▶

GET /api/tools/slug/:slug

Returns a single tool's full details including reviews and bookmark count. Increments viewCount once per visitor per day (cookie-based dedup).

Path Parameters

Param	Type	Description
slug	string	Tool URL slug

Response

200 — Full tool detail

{
  "success": true,
  "data": {
    "id": "tool_abc",
    "slug": "my-ai-tool",
    "name": "My AI Tool",
    "description": "Full description...",
    "websiteUrl": "https://mytool.com",
    "screenshotUrls": ["https://..."],
    "features": [{ "title": "Feature 1", "description": "..." }],
    "useCases": ["Marketing automation"],
    "pros": "Easy to use, great API",
    "cons": "No mobile app",
    "platform": ["Web", "API"],
    "languages": ["English"],
    "apiAccess": true,
    "typeMetadata": {},
    "reviews": [
      {
        "id": "rev_abc",
        "content": "Great tool!",
        "rating": 5,
        "createdAt": "2026-03-10T00:00:00.000Z",
        "user": { "id": "usr_xyz", "username": "reviewer" }
      }
    ],
    "_count": { "bookmarks": 42 }
  }
}

GET

Published Tool Slugs

▶

GET /api/tools/slugs

Returns an array of published tool slugs. Used by sub-sites to build sitemaps and pre-render pages.

Query Parameters

Param	Type	Default	Description
limit	number	500	Max slugs to return (max 500)
type	string	—	Filter by toolType e.g. `lawyer`

Response

200 — Slugs

{
  "success": true,
  "data": {
    "slugs": ["my-ai-tool", "another-tool", "best-ai-tool"],
    "total": 3
  }
}

GET

Check Slug Availability

▶

GET /api/tools/check-slug?slug=my-tool

Query Parameters

Param	Type	Required	Description
slug	string	required	Slug to check (lowercase, hyphens only)

Response

200 — Availability

{ "success": true, "data": { "slug": "my-tool", "available": true } }

POST

Track Click

▶

POST /api/tools/:id/click

Increments the tool's click count when a visitor clicks through to the tool's website. No auth required. Fire-and-forget — does not block the response.

Response

200 — Tracked

{ "success": true, "message": "Click tracked." }

POST

Create Tool

🔒 Auth Required ▶

POST /api/tools

Creates a new tool listing. Requires an active subscription. The plan's max_tools setting limits how many tools a creator can publish.

Request Body

Field	Type	Required	Description
name	string	required	2–100 characters
websiteUrl	string (URL)	required	Tool's website
toolType	string	required	e.g. `general`, `lawyer`, `video`, `real-estate`
pricingModel	enum	required	`free` \| `freemium` \| `paid` \| `enterprise`
slug	string	optional	Auto-generated from name if omitted
singleLineDescription	string	optional	Max 120 chars — used in cards
description	string	optional	Full description, max 5000 chars
logoUrl	string (URL)	optional	Tool logo image URL
screenshotUrls	string[]	optional	Up to 10 screenshot URLs
targetIndustries	string[]	optional	Up to 20 industry slugs
tags	string[]	optional	Up to 30 tags
features	object[]	optional	`[{ title, description }]` — up to 20
useCases	string[]	optional	Up to 20 use case strings
pros	string	optional	Max 2000 chars
cons	string	optional	Max 2000 chars
startingPrice	number	optional	Starting price in USD
apiAccess	boolean	optional	Does the tool have an API?
platform	string[]	optional	e.g. `["Web", "iOS", "API"]`
languages	string[]	optional	Supported languages
typeMetadata	object	optional	Type-specific data (see Video/Lawyer/RE metadata schemas)
status	enum	optional	`draft` \| `active` — defaults to `draft`

Request Example

JSON

{
  "name": "ContractAI Pro",
  "websiteUrl": "https://contractai.io",
  "toolType": "lawyer",
  "pricingModel": "paid",
  "startingPrice": 49,
  "singleLineDescription": "AI-powered contract review in seconds",
  "targetIndustries": ["legal", "corporate"],
  "tags": ["contract", "legal-ai", "review"],
  "status": "active",
  "typeMetadata": {
    "practiceAreas": ["contract-review", "corporate"],
    "functional": ["document-drafting", "contract-analysis"],
    "compliance": {
      "gdpr": true,
      "soc2": true,
      "trainsOnUserData": false
    }
  }
}

Response

201 — Tool created

{
  "success": true,
  "message": "Tool created successfully.",
  "data": { "tool": { /* full tool object */ } }
}

⚠️ Returns 402 PLAN_LIMIT_EXCEEDED if the user has reached their plan's tool limit. Requires active subscription — returns 402 without one.

PUT

Update Tool

🔒 Auth Required ▶

PUT /api/tools/:id

Updates an existing tool. All fields are optional. Only the tool owner (or an admin) can update a tool. Triggers sub-site revalidation.

Path Parameters

Param	Type	Description
id	string	Tool ID (UUID)

Request Body

Same fields as Create Tool — all optional. Omitted fields are not changed.

Response

200 — Updated tool

{ "success": true, "message": "Tool updated successfully.", "data": { "tool": { /* ... */ } } }

DELETE

Delete Tool

🔒 Auth Required ▶

DELETE /api/tools/:id

Permanently deletes a tool and all its reviews/bookmarks (cascade). Only the owner or an admin can delete. Triggers sub-site revalidation.

Response

200 — Deleted

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

POST

Create Review

🔒 Auth Required ▶

POST /api/tools/:id/reviews

Submits a written review with a star rating for a tool. One review per user per tool — returns 409 Conflict if already reviewed.

Request Body

Field	Type	Required	Description
content	string	required	Review text — 10 to 1000 characters
rating	number	required	Integer 1–5

Response

201 — Review created

{
  "success": true,
  "data": {
    "review": {
      "id": "rev_abc",
      "content": "Amazing tool, very intuitive!",
      "rating": 5,
      "createdAt": "2026-04-22T10:00:00.000Z",
      "user": { "id": "usr_abc", "username": "johndoe" }
    }
  }
}

POST

Toggle Bookmark

🔒 Auth Required ▶

POST /api/tools/:id/bookmark

Toggles a bookmark on a tool. Call again to unbookmark.

Response

200 — Toggle result

{ "success": true, "data": { "bookmarked": true } }
// or { "bookmarked": false } when unbookmarked

POST

Toggle Upvote

🔒 Auth Required ▶

POST /api/tools/:id/upvote

Toggles an upvote on a tool. Increments or decrements upvoteCount.

Response

200 — Toggle result

{ "success": true, "data": { "upvoted": true } }

POST

Rate Tool

🔒 Auth Required ▶

POST /api/tools/:id/rate

Submits a star-only rating (1–5) without a written review. Upserts — calling again updates the existing rating.

Request Body

Field	Type	Required	Description
rating	number	required	Integer 1–5

Response

200

{ "success": true, "data": { "rating": 4 } }

GET

Admin List All Tools

🛡 Admin Only ▶

GET /api/tools/admin/all

Returns all tools across all statuses (draft, active, archived) with extended admin filters. No caching — always live data.

Extra Admin Query Params (in addition to standard list params)

Param	Type	Description
status	enum	`draft` \| `active` \| `archived`
verified	boolean	Filter by verification status
apiAccess	boolean	Filter by API access flag
minPrice	number	Minimum starting price
maxPrice	number	Maximum starting price

PATCH

Update Tool Status

🛡 Admin Only ▶

PATCH /api/tools/:id/status

Request Body

Field	Type	Required	Description
status	enum	required	`draft` \| `active` \| `archived`
featured	boolean	optional	Mark as featured
verified	boolean	optional	Mark as verified

POST

Bulk Import Tools

🛡 Admin Only ▶

POST /api/tools/bulk

Imports up to 100 tools in a single request. Each tool is processed independently — failures are reported without aborting the batch. Bypasses plan limits.

Request Body

Field	Type	Required	Description
tools	object[]	required	Array of tool objects (1–100). Same schema as Create Tool.
publishImmediately	boolean	optional	If true, tools are set to `active`. Default: `true`

Response

200 — Batch result

{
  "success": true,
  "data": {
    "summary": { "total": 5, "created": 4, "skipped": 1, "failed": 0 },
    "created": [ /* tool objects */ ],
    "skipped": [{ "name": "Duplicate Tool", "reason": "Duplicate name for this user" }],
    "failed": []
  }
}

PATCH

Bulk Update Tools

🛡 Admin Only ▶

PATCH /api/tools/bulk

Request Body

Field	Type	Required	Description
tools	object[]	required	Array of partial tool objects, each must include `id` (UUID)

Request Example

JSON

{
  "tools": [
    { "id": "tool_abc", "featured": true, "status": "active" },
    { "id": "tool_def", "pricingModel": "freemium" }
  ]
}

🔧 Tools

List Tools

Homepage Listing

Featured Tools

Get Tool by Slug

Published Tool Slugs

Check Slug Availability

Track Click

Authenticated Endpoints

Create Tool

Update Tool

Delete Tool

Create Review

Toggle Bookmark

Toggle Upvote

Rate Tool

Admin Endpoints

Admin List All Tools

Update Tool Status

Bulk Import Tools

Bulk Update Tools