v1.0
API Reference / Users

👤 Users

User profile management, password changes, bookmarks, and admin user management. All endpoints require authentication.

Base Path /api/users
GET

Get My Profile

🔒 Auth Required ▶
GET /api/users/profile

Returns the full profile of the currently authenticated user.

Response
200 — User profile
{
  "success": true,
  "data": {
    "user": {
      "id":                 "usr_abc123",
      "username":           "johndoe",
      "email":              "john@example.com",
      "role":               "user",
      "avatar":             "https://example.com/avatar.jpg",
      "language":           "en",
      "timezone":           "UTC",
      "preferences": { "default_results_per_page": 25, "default_order_type": "DESC" },
      "status":             "active",
      "isSubscribed":       true,
      "subscriptionStatus": "active",
      "haveTrial":          false,
      "trialEnd":           null,
      "lastActivity":       "2026-04-22T10:00:00.000Z",
      "createdAt":          "2026-01-15T08:00:00.000Z",
      "_count": { "tools": 4, "reviews": 12, "bookmarks": 7 },
      "subscription": {
        "status":            "active",
        "periodEnd":         "2026-05-15T00:00:00.000Z",
        "cancelAtPeriodEnd": false,
        "plan": { "id": "plan_premium", "name": "Premium" }
      }
      // subscription is null if the user has never subscribed
    }
  }
}
PUT

Update Profile

🔒 Auth Required ▶
PUT /api/users/profile

Updates the user's profile fields. All fields are optional — only provided fields are updated.

Request Body
FieldTypeRequiredDescription
usernamestringoptional3–20 chars, letters/numbers/underscore
avatarstring (URL)optionalProfile picture URL
languagestringoptionalLanguage code e.g. en, es
timezonestringoptionalIANA timezone e.g. America/New_York
preferencesobjectoptionalCustom preferences JSON object
Request Example
JSON
{
  "username": "johndoe_updated",
  "language": "es",
  "timezone": "America/New_York",
  "preferences": { "default_results_per_page": 50 }
}
Response
200 — Updated
{
  "success": true,
  "message": "Profile updated successfully.",
  "data": { "user": { /* updated user object */ } }
}
PUT

Change Password

🔒 Auth Required ▶
PUT /api/users/change-password
Request Body
FieldTypeRequiredDescription
oldPasswordstringrequiredCurrent password (8–64 chars)
newPasswordstringrequiredNew password (8–64 chars), must differ from old
confirmPasswordstringrequiredMust match newPassword
Request Example
JSON
{
  "oldPassword": "OldPass123",
  "newPassword": "NewSecurePass456",
  "confirmPassword": "NewSecurePass456"
}
Response
200 — Success
{ "success": true, "message": "Password changed successfully." }
401 — Wrong current password
{ "success": false, "errorCode": "WRONG_PASSWORD", "message": "Current password is incorrect." }
GET

Get Bookmarks

🔒 Auth Required ▶
GET /api/users/bookmarks

Returns a paginated list of tools the user has bookmarked.

Query Parameters
ParamTypeDefaultDescription
pagenumber1Page number
limitnumber20Results per page (max 100)
Response
200 — Bookmarks
{
  "success": true,
  "data": {
    "bookmarks": [
      {
        "id": "bm_123",
        "toolId": "tool_abc",
        "createdAt": "2026-04-10T00:00:00.000Z",
        "tool": {
          "id": "tool_abc",
          "slug": "my-ai-tool",
          "name": "My AI Tool",
          "singleLineDescription": "AI that does everything",
          "logoUrl": "https://example.com/logo.png",
          "toolType": "general",
          "pricingModel": "freemium",
          "rating": 4.5
        }
      }
    ],
    "pagination": { "total": 12, "page": 1, "limit": 20, "totalPages": 1 }
  }
}

Admin Endpoints

GET

Get All Users

🛡 Admin Only ▶
GET /api/users/admin/all
Query Parameters
ParamTypeDefaultDescription
pagenumber1Page number
limitnumber20Results per page
searchstring—Search by email or username
Response
200 — Paginated users
{
  "success": true,
  "data": {
    "users": [
      {
        "id":                 "usr_abc",
        "username":           "johndoe",
        "email":              "john@example.com",
        "role":               "user",
        "status":             "active",
        "isSubscribed":       true,
        "subscriptionStatus": "active",
        "createdAt":          "2026-01-15T08:00:00.000Z",
        "lastActivity":       "2026-04-26T10:00:00.000Z",
        "_count": { "tools": 4 },
        "subscription": {
          "status":    "active",
          "periodEnd": "2026-05-15T00:00:00.000Z",
          "plan": { "id": "plan_premium", "name": "Premium" }
        }
      }
    ],
    "pagination": { "total": 150, "page": 1, "limit": 20, "totalPages": 8 }
  }
}
GET

Get User by ID

🛡 Admin Only ▶
GET /api/users/admin/:id
Path Parameters
ParamTypeDescription
idstringUser ID
Response
200 — Full user profile
{
  "success": true,
  "data": {
    "user": {
      "id":                 "usr_abc",
      "username":           "johndoe",
      "email":              "john@example.com",
      "role":               "user",
      "avatar":             "https://...",
      "language":           "en",
      "timezone":           "UTC",
      "status":             "active",
      "isSubscribed":       true,
      "subscriptionStatus": "active",
      "haveTrial":          false,
      "trialEnd":           null,
      "lastActivity":       "2026-04-26T10:00:00.000Z",
      "createdAt":          "2026-01-15T08:00:00.000Z",
      "preferences": { "default_results_per_page": 25, "default_order_type": "DESC" },
      "_count": { "tools": 4, "reviews": 12, "bookmarks": 7 },
      "subscription": {
        "status":             "active",
        "periodEnd":          "2026-05-15T00:00:00.000Z",
        "cancelAtPeriodEnd":  false,
        "plan": { "id": "plan_premium", "name": "Premium" }
      }
    }
  }
}
404 — Not found
{ "success": false, "errorCode": "USER_NOT_FOUND", "message": "User not found." }
GET

Get User's Tools

🛡 Admin Only ▶
GET /api/users/admin/tools

Returns all tools belonging to a specific user, identified by username or email.

Query Parameters
ParamTypeRequiredDescription
usernamestringone ofTarget user's username
emailstringone ofTarget user's email
pagenumberoptionalPage number (default 1)
limitnumberoptionalResults per page (default 20)
Response
200 — User's tools
{
  "success": true,
  "data": {
    "user": {
      "id": "usr_abc", "username": "johndoe",
      "email": "john@example.com", "role": "user", "status": "active"
    },
    "tools": [
      {
        "id":                    "tool_abc",
        "slug":                  "my-ai-tool",
        "name":                  "My AI Tool",
        "singleLineDescription": "AI that does everything",
        "toolType":              "general",
        "pricingModel":          "freemium",
        "startingPrice":         0,
        "status":                "active",
        "featured":              false,
        "verified":              true,
        "viewCount":             1240,
        "rating":                4.3,
        "reviewCount":           18,
        "createdAt":             "2026-02-01T00:00:00.000Z",
        "publishedAt":           "2026-02-02T00:00:00.000Z"
      }
    ],
    "pagination": { "total": 3, "page": 1, "limit": 20, "totalPages": 1 }
  }
}
PATCH

Update User Status

🛡 Admin Only ▶
PATCH /api/users/admin/:id/status

Updates a user's account status. Suspended and banned users are blocked from logging in and using the API.

Path Parameters
ParamTypeDescription
idstringUser ID
Request Body
FieldTypeRequiredValues
statusenumrequiredactive | suspended | banned
Request Example
JSON
{ "status": "suspended" }
Response
200 — Updated
{
  "success": true,
  "message": "User status updated.",
  "data": { "user": { "id": "usr_abc", "status": "suspended" } }
}