AI Tools Directory API Reference

Complete REST API documentation for the AI Tools Directory backend — built on Cloudflare Workers, Hono, and D1. All endpoints return JSON.

Base URL https://ai-tools-backend.workers.dev/api

⚡ Environments

Production	https://ai-tools-backend.workers.dev/api
Local Dev	http://localhost:8787/api
Health	GET /health

🔐 Authentication

Most endpoints require a valid JWT access token. Tokens are issued after login or email verification and expire in 15 minutes. Refresh tokens last 30 days.

Option 1 — Authorization Header (recommended)

HTTP

Authorization: Bearer <access_token>

Option 2 — Cookie (browser clients)

Cookie

access_token=<access_token>

ℹ️ All 🔒 Auth Required endpoints will return 401 Unauthorized without a valid token. Admin-only endpoints return 403 Forbidden for non-admin users.

Error Format

All errors follow a consistent JSON envelope regardless of the error type.

JSON — Error Response

{
  "success": false,
  "errorCode": "VALIDATION_ERROR",
  "message": "Validation failed",
  "errors": [         // present for validation errors only
    { "field": "email", "message": "Invalid email address" }
  ]
}

HTTP Status Codes

200

OK — Success

201

Created

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

409

Conflict

422

Unprocessable

500

Server Error

API Modules

Authentication

Register, login, email OTP verification, Google OAuth, token refresh, and logout.

POST /register POST /login GET /me +5 more

Subscription & Payments

Stripe-powered plans, checkout sessions, direct card payment, plan upgrades, billing portal, and invoices.

GET /plans POST /checkout +9 more

Users

User profiles, password change, bookmarks, and admin user management.

GET /profile PUT /profile +5 more

Tools

Full CRUD for AI tool listings — create, list, search, review, rate, bookmark, upvote, bulk import.

GET / POST / POST /bulk +12 more

Blogs

Blog post CRUD with slug routing, view tracking, helpful/not-helpful feedback, full-text search, and admin bulk import.

GET / GET /:slug POST /bulk +5 more

AI for Lawyers

Specialized lawyer tool listing with practice area, compliance, and functional filters.

GET / GET /filters GET /:slug

AI for Real Estate

Real estate tool listing with property type, functional, and compliance standard filters.

GET / GET /filters GET /:slug

AI for Videos

Video AI tool listing filtered by generation method, use case, and production stage.

GET / GET /filters

Tool Ranking Strategy

How tools are ordered — rank score formula, featured section rules, CDN cache TTLs, scheduling, and cold-start handling for new publishers.

Concept Featured Cache Scheduling

Homepage Listing & Promotion

Slot-layer architecture, new tool step-down fade, paid promotion (flat-fee slots), dedicated homepage route design, and cache strategy.

Concept Promotion New Tools Route