Products API Endpoints — Inventory CRUD and Stock

The Products API manages the entire AutoPart Pro inventory. Public read access lets any visitor browse the catalog, while authenticated users can look up individual parts. All write operations — creating, updating, and deleting products — are restricted to accounts with the admin role. SKUs are the unique business identifier for each part and are automatically uppercased before storage. The PUT endpoint also fires an internal low-stock event via stockEmitter whenever an update brings a product’s stock at or below its configured minimum.

GET /api/products

Returns all products in the inventory ordered from newest to oldest (created_at DESC). No authentication is required. This is the primary endpoint for populating the storefront catalog and the admin inventory table.

Example request

curl -X GET https://api.autopartpro.com/api/products

Responses

success

boolean

true on a successful fetch.

data

array

Array of product objects.

Show product fields

integer

Auto-incremented primary key.

sku

string

Stock-Keeping Unit — unique identifier for the part (stored uppercase).

name

string

Human-readable product name.

brand

string

Manufacturer or brand of the part.

compatible_cars

string

Comma-separated list of compatible vehicle makes/models.

price

float

Unit sale price. Always returned as a JavaScript float.

stock

integer

Current units available in inventory.

min_stock

integer

Minimum stock threshold. When stock <= min_stock a low-stock alert is triggered.

image_url

string

URL of the product image, or null if not set.

GET /api/products/:id

Fetches a single product by its database ID. Requires a valid Bearer token. Use this to populate a product detail page or a pre-filled edit form in the admin panel.

Path parameters

integer

required

The database ID of the product to retrieve.

Example request

curl -X GET https://api.autopartpro.com/api/products/7 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6NDIsInJvbGUiOiJjbGllbnQiLCJpYXQiOjE3MTA4NjQwMDAsImV4cCI6MTcxMDg2NzYwMH0.xyz789"

Responses

success

boolean

true when the product is found.

data

object

The full product object. Fields are identical to those described in GET /api/products.

200 — OK

{
  "success": true,
  "data": {
    "id": 7,
    "sku": "FILT-ACE-001",
    "name": "Filtro de Aceite Premium",
    "brand": "Bosch",
    "compatible_cars": "Toyota Corolla 2018-2023, Honda Civic 2019-2022",
    "price": 12.99,
    "stock": 85,
    "min_stock": 10,
    "image_url": "https://cdn.autopartpro.com/images/filt-ace-001.jpg",
    "category": "Filtros",
    "description": "Filtro de aceite de alto rendimiento con vida útil extendida.",
    "created_at": "2024-03-15T10:30:00.000Z",
    "updated_at": "2024-03-18T08:00:00.000Z"
  }
}

404 — Not found

{
  "success": false,
  "message": "Producto no encontrado."
}

POST /api/products

Creates a new product in the inventory. Requires a valid Bearer token with the admin role. SKUs are automatically uppercased before being inserted. The sku column has a unique constraint — submitting a duplicate SKU returns a 400 error.

The sku, name, and brand fields are required. All other fields are optional and default to null or 0 if omitted.

Request body

sku

string

required

Unique stock-keeping unit identifier. Automatically converted to uppercase before storage (e.g. "filt-ace-002" → "FILT-ACE-002").

name

string

required

Human-readable product name.

brand

string

required

Manufacturer or brand name.

compatible_cars

string

Comma-separated string of compatible vehicle makes and models.

price

number

Unit sale price. Must be >= 0.

stock

integer

Initial stock quantity. Must be an integer >= 0.

image_url

string

Publicly accessible URL for the product image.

description

string

Free-text description of the product.

Example request

curl -X POST https://api.autopartpro.com/api/products \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiNm9sZSI6ImFkbWluIiwiaWF0IjoxNzEwODY0MDAwLCJleHAiOjE3MTA4Njc2MDB9.admintoken" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "PAST-FRE-007",
    "name": "Pastillas de Freno Delanteras",
    "brand": "Brembo",
    "compatible_cars": "Nissan Sentra 2017-2022, Volkswagen Jetta 2016-2021",
    "price": 34.50,
    "stock": 120,
    "category": "Frenos",
    "description": "Pastillas de freno de alto rendimiento con bajo nivel de polvo.",
    "image_url": "https://cdn.autopartpro.com/images/past-fre-007.jpg"
  }'

Responses

success

boolean

true on successful creation.

message

string

Confirmation: "Autoparte registrada con éxito"

productId

integer

The auto-incremented ID of the newly created product row.

201 — Created

{
  "success": true,
  "message": "Autoparte registrada con éxito",
  "productId": 23
}

400 — Missing required fields

{
  "success": false,
  "message": "Faltan campos obligatorios: sku, name y brand son requeridos."
}

400 — Duplicate SKU

{
  "success": false,
  "message": "El SKU 'PAST-FRE-007' ya está registrado en el inventario."
}

PUT /api/products/:id

Partially updates an existing product. Only the fields included in the request body are modified — fields that are omitted remain unchanged. Requires a valid Bearer token with the admin role. After every successful update, the server re-fetches the product and emits a low-stock event via stockEmitter if the current stock is at or below min_stock.

At least one field must be provided in the request body. Sending an empty object returns a server error.

Path parameters

integer

required

The database ID of the product to update.

Request body

Any combination of the following fields. All are optional, but at least one must be present.

sku

string

New SKU value. Must be unique. Will be rejected with 400 if it collides with another product.

name

string

Updated product name.

brand

string

Updated brand.

compatible_cars

string

Updated compatible vehicles string.

price

number

Updated unit price.

stock

integer

Updated stock level. If the new value is <= min_stock, a low-stock event is fired server-side.

min_stock

integer

Updated minimum stock threshold.

image_url

string

Updated image URL.

description

string

Updated description.

Example request

curl -X PUT https://api.autopartpro.com/api/products/23 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiNm9sZSI6ImFkbWluIiwiaWF0IjoxNzEwODY0MDAwLCJleHAiOjE3MTA4Njc2MDB9.admintoken" \
  -H "Content-Type: application/json" \
  -d '{
    "price": 38.00,
    "stock": 5
  }'

Responses

success

boolean

true when the update is applied.

message

string

"Autoparte actualizada con éxito."

200 — OK

{
  "success": true,
  "message": "Autoparte actualizada con éxito."
}

404 — Not found

{
  "success": false,
  "message": "Producto no encontrado."
}

400 — Duplicate SKU

{
  "success": false,
  "message": "El SKU ingresado ya pertenece a otro producto."
}

DELETE /api/products/:id

Permanently removes a product from the inventory. Requires a valid Bearer token with the admin role. This action is irreversible — consider setting stock to 0 instead if you want to keep sales history intact.

Path parameters

integer

required

The database ID of the product to delete.

Example request

curl -X DELETE https://api.autopartpro.com/api/products/23 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiNm9sZSI6ImFkbWluIiwiaWF0IjoxNzEwODY0MDAwLCJleHAiOjE3MTA4Njc2MDB9.admintoken"

Responses

success

boolean

true when the product is deleted.

message

string

"Autoparte eliminada del inventario."

200 — OK

{
  "success": true,
  "message": "Autoparte eliminada del inventario."
}

404 — Not found

{
  "success": false,
  "message": "Producto no encontrado."
}

GET /api/products/low-stock

Returns all products whose current stock is at or below their configured min_stock threshold. Requires a valid Bearer token. Use this endpoint to power low-stock alert dashboards or automated reorder notifications.

Because Express registers routes in order, /low-stock is defined before /:id in the router file. This ensures the literal segment low-stock is not interpreted as a numeric ID.

Example request

curl -X GET https://api.autopartpro.com/api/products/low-stock \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiNm9sZSI6ImFkbWluIiwiaWF0IjoxNzEwODY0MDAwLCJleHAiOjE3MTA4Njc2MDB9.admintoken"

Responses

success

boolean

true on a successful fetch.

data

array

Array of low-stock entries.

Show item fields

name

string

Product name.

stock

integer

Current stock level (at or below min_stock).

200 — OK

{
  "success": true,
  "data": [
    { "name": "Pastillas de Freno Delanteras", "stock": 3 },
    { "name": "Bujías NGK Iridium", "stock": 0 }
  ]
}

Overview

Endpoints

Products API Endpoints — Inventory CRUD and Stock

GET /api/products

Example request

Responses

GET /api/products/:id

Path parameters

Example request

Responses

POST /api/products

Request body

Example request

Responses

PUT /api/products/:id

Path parameters

Request body

Example request

Responses

DELETE /api/products/:id

Path parameters

Example request

Responses

GET /api/products/low-stock

Example request

Responses

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /api/products

​Example request

​Responses

​GET /api/products/:id

​Path parameters

​Example request

​Responses

​POST /api/products

​Request body

​Example request

​Responses

​PUT /api/products/:id

​Path parameters

​Request body

​Example request

​Responses

​DELETE /api/products/:id

​Path parameters

​Example request

​Responses

​GET /api/products/low-stock

​Example request

​Responses

Build docs developers (and LLMs) love

GET /api/products

Example request

Responses

GET /api/products/:id

Path parameters

Example request

Responses

POST /api/products

Request body

Example request

Responses

PUT /api/products/:id

Path parameters

Request body

Example request

Responses

DELETE /api/products/:id

Path parameters

Example request

Responses

GET /api/products/low-stock

Example request

Responses