Scrapizoo Category API Docs

Base URL

http://localhost:8000/api/category

All routes below are prefixed with this base URL.

1️⃣ Get All Categories

GET /show

Description

Fetch all categories with their subcategories.

Success Response (200)


{
  "success": true,
  "count": 1,
  

  "data": [
    {
      "_id": "69a5b5e4930e55ca0f4c92d0",
            "name": "Plastic",
            "icon": "📦",
            "description": "Plastic bottles, containers, bags, and other plastic items",
            "subcategories": [
                {
                    "name": "Bottles",
                    "_id": "69a5b5f2930e55ca0f4c92d7"
                }
            ],
            "createdAt": "2026-03-02T16:08:04.877Z",
            "updatedAt": "2026-03-02T16:08:18.609Z",
            "__v": 1
    }
  ]
}

Error Response (500)

500 → Server Error (Database or internal failure)

2️⃣ Create Category

POST /create (Protected - Admin JWT Required)

Description

Create a new category with optional subcategories.

Request Body

Content-Type: application/json


{ "name": "Paper", "icon": "📄", "description": "All types of paper waste including newspapers, books, cardboard", "subcategories": [] }

Success Response (201)


{
    "success": true,
    "message": "Category created successfully",
    "data": {
        "name": "Paper",
        "icon": "📄",
        "description": "All types of paper waste including newspapers, books, cardboard",
        "subcategories": [],
        "_id": "69abcdb6dd4ab4f2eea9048a",
        "createdAt": "2026-03-07T07:03:18.620Z",
        "updatedAt": "2026-03-07T07:03:18.620Z",
        "__v": 0
    }
}

Error Responses

400 → Category already exists / Failed to create category
401/403 → Invalid or missing admin JWT (from verifyAdminJWT middleware)

3️⃣ Update Category

POST /update-category (Protected - Admin JWT Required)

Description

Update an existing category by its ID. All fields are optional except _id.

Request Body

Content-Type: application/json


{
  "_id": "6720a8d8f1c2b3a5e4d90123",
  "name": "Paper",
  "icon": "📄",
  "description": "Updated description",
  "subcategories": [
    { "_id": "6720a8e6f1c2b3a5e4d90124", "name": "Newspaper" },
    { "_id": "6720a8f3f1c2b3a5e4d90125", "name": "Books" },
    { "name": "CardBoard" }
  ]
}

Success Response (200)


{
  "success": true,
  "message": "Category updated successfully",
  "data": {
    "_id": "6720a8d8f1c2b3a5e4d90123",
    "name": "Paper",
    "icon": "📄",
    "description": "Updated description",
    "subcategories": [
      { "_id": "6720a8e6f1c2b3a5e4d90124", "name": "Newspaper" },
      { "_id": "6720a8f3f1c2b3a5e4d90125", "name": "Books" },
      { "_id": "6720a9a1f1c2b3a5e4d90126", "name": "CardBoard" }
    ],
    "createdAt": "2024-10-28T10:15:00.000Z",
    "updatedAt": "2024-10-28T10:20:00.000Z",
    "__v": 1
  }
}

Error Responses

404 → Category not found
400 → Failed to update category
401/403 → Invalid or missing admin JWT

4️⃣ Delete Category

POST /delete-category (Protected - Admin JWT Required)

Description

Delete a category by its ID.

Request Body

Content-Type: application/json


{
  "id": "6720a8d8f1c2b3a5e4d90123"
}

Success Response (200)


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

Error Responses

404 → Category not found
500 → Failed to delete category (Server error)
401/403 → Invalid or missing admin JWT

5️⃣ Add SubCategory

POST /add-subcategories (Protected - Admin JWT Required)

Description

Add a new subcategory to an existing category.

Request Body

Content-Type: application/json


{
  "id": "6720a8d8f1c2b3a5e4d90123",   // Category ID
  "name": "Smart Watches"            // SubCategory name
}

Success Response (200)


{
  "success": true,
  "message": "SubCategory added successfully",
  "data": {
    "_id": "6720a8d8f1c2b3a5e4d90123",
    "name": "Paper",
    "icon": "📄",
    "description": "Electronic waste items",
    "subcategories": [
      { "_id": "6720a8e6f1c2b3a5e4d90124", "name": "Newspaper" },
      { "_id": "6720a8f3f1c2b3a5e4d90125", "name": "Books" },
      { "_id": "6720aa11f1c2b3a5e4d90127", "name": "Smart Watches" }
    ]
  }
}

Error Responses

404 → Category not found
400 → SubCategory with this name already exists / Failed to add Subcategory
401/403 → Invalid or missing admin JWT

6️⃣ Update SubCategory

POST /update-subcategories (Protected - Admin JWT Required)

Description

Update a single subcategory inside a category.

Request Body

Content-Type: application/json


{
  "categoryId": "6720a8d8f1c2b3a5e4d90123",
  "id": "6720a8e6f1c2b3a5e4d90124",   // SubCategory _id
  "name": "Smart Phones"
}

Success Response (200)


{
  "success": true,
  "message": "SubCategory updated successfully",
  "data": {
    "_id": "6720a8d8f1c2b3a5e4d90123",
    "name": "Paper",
    "icon": "📄",
    "description": "Electronic waste items",
    "subcategories": [
      { "_id": "6720a8e6f1c2b3a5e4d90124", "name": "Smart Phones" }
    ]
  }
}

Error Responses

404 → Category not found / SubCategory not found
400 → Failed to update Subcategory
401/403 → Invalid or missing admin JWT

7️⃣ Delete SubCategory

POST /delete-subcategory (Protected - Admin JWT Required)

Description

Delete a subcategory from a category.

Request Body

Content-Type: application/json


{
  "categoryId": "6720a8d8f1c2b3a5e4d90123",
  "id": "6720a8e6f1c2b3a5e4d90124"    // SubCategory _id
}

Success Response (200)


{
  "success": true,
  "message": "SubCategory deleted successfully",
  "data": {
    "_id": "6720a8d8f1c2b3a5e4d90123",
    "name": "Paper",
    "icon": "📄",
    "description": "Electronic waste items",
    "subcategories": [
      // remaining subcategories
    ]
  }
}

Error Responses

404 → Category not found
500 → Failed to delete Subcategory (Server error)
401/403 → Invalid or missing admin JWT