Skip to main content
The Products API provides endpoints for listing, searching, retrieving, and creating products.

​
GET /api/products

Retrieve a paginated list of products.

​
Authentication

Not required.

​
Query Parameters

​
page
integer
default:"1"
Page number for pagination
​
limit
integer
default:"10"
Number of products per page

​
Response

​
products
array
Array of product objects
​
total
integer
Total number of products
​
page
integer
Current page number
​
limit
integer
Products per page
​
totalPages
integer
Total number of pages

​
Example Request

curl -X GET "http://localhost:3000/api/products?page=1&limit=10"

​
Example Response

{
  "products": [
    {
      "id": 1,
      "name": "Laptop",
      "description": "High-performance laptop",
      "price": "999.99",
      "stock": 50,
      "category": "Electronics"
    },
    {
      "id": 2,
      "name": "Wireless Mouse",
      "description": "Ergonomic wireless mouse",
      "price": "29.99",
      "stock": 200,
      "category": "Accessories"
    }
  ],
  "total": 45,
  "page": 1,
  "limit": 10,
  "totalPages": 5
}

​
GET /api/products/search

Search products using fuzzy search.

​
Authentication

Not required.

​
Query Parameters

​
q
string
required
Search query string (searches in name and description fields)

​
Response

​
products
array
Array of matching product objects
​
count
integer
Number of results found

​
Example Request

curl -X GET "http://localhost:3000/api/products/search?q=laptop"

​
Example Response

{
  "products": [
    {
      "id": 1,
      "name": "Laptop",
      "description": "High-performance laptop",
      "price": "999.99",
      "stock": 50,
      "category": "Electronics"
    }
  ],
  "count": 1
}

​
Error Responses

  • 400 Bad Request - Search query ‘q’ is required
  • 500 Internal Server Error - Search failed
The search uses Fuse.js for fuzzy matching with a threshold of 0.4, searching across product names and descriptions.

​
GET /api/products/:id

Retrieve a single product by ID.

​
Authentication

Not required.

​
Path Parameters

​
id
integer
required
Product ID

​
Response

​
product
object
Product information

​
Example Request

curl -X GET http://localhost:3000/api/products/1

​
Example Response

{
  "product": {
    "id": 1,
    "name": "Laptop",
    "description": "High-performance laptop",
    "price": "999.99",
    "stock": 50,
    "category": "Electronics"
  }
}

​
Error Responses

  • 404 Not Found - Product not found
  • 500 Internal Server Error - Failed to fetch product

​
POST /api/products

Create a new product.

​
Authentication

Required. Include JWT token in Authorization header.

​
Request Body

​
name
string
required
Product name
​
price
decimal
required
Product price
​
description
string
Product description
​
stock
integer
default:"0"
Initial stock quantity
​
category
string
Product category

​
Response

​
product
object
Created product information

​
Example Request

curl -X POST http://localhost:3000/api/products \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mechanical Keyboard",
    "description": "RGB mechanical keyboard with cherry switches",
    "price": 149.99,
    "stock": 75,
    "category": "Accessories"
  }'

​
Example Response

{
  "product": {
    "id": 3,
    "name": "Mechanical Keyboard",
    "description": "RGB mechanical keyboard with cherry switches",
    "price": "149.99",
    "stock": 75,
    "category": "Accessories"
  }
}

​
Error Responses

  • 400 Bad Request - Name and price are required
  • 401 Unauthorized - Missing or invalid authentication token
  • 500 Internal Server Error - Failed to create product

Build docs developers (and LLMs) love

Get started for freeTalk to us