Developers

API Documentation

Three endpoints: search the Home & Kitchen catalog, inspect a product, and place a simulated order.

This API is currently unauthenticated and backed by a fixed demo catalog. Orders placed today are simulated — no real payment is collected and no real product ships. Real catalog data, payment processing, and access controls will follow before general availability.

01GET /api/products/search

Returns product summaries matching a keyword and/or category. At least one of query or category is required. If both are given, results must match both.

Name	Type	Required	Description
`query`	string	One of query/category required	Case-insensitive substring match against name and description, e.g. `french press`
`category`	string	One of query/category required	Exact match: `cookware`, `small_appliances`, `storage_organization`, `home_decor`

curl "https://houseproducts.odellblackmoniii.com/api/products/search?category=cookware"

{
  "count": 5,
  "results": [
    { "id": "cw-001", "name": "8-Cup Glass French Press", "category": "cookware", "price": 34.99, "currency": "USD", "in_stock": true },
    { "id": "cw-002", "name": "12-Inch Cast Iron Skillet", "category": "cookware", "price": 44.5, "currency": "USD", "in_stock": true },
    { "id": "cw-003", "name": "3-Quart Enameled Dutch Oven", "category": "cookware", "price": 89, "currency": "USD", "in_stock": true },
    { "id": "cw-004", "name": "Nonstick 10-Piece Cookware Set", "category": "cookware", "price": 129.99, "currency": "USD", "in_stock": false },
    { "id": "cw-005", "name": "Stainless Steel Mixing Bowl Set", "category": "cookware", "price": 28.75, "currency": "USD", "in_stock": true }
  ]
}

02GET /api/products/detail

Returns full detail for a single product, including sku and description.

Name	Type	Required	Description
`id`	string	Yes	Product id, as returned by search

curl "https://houseproducts.odellblackmoniii.com/api/products/detail?id=hd-005"

{
  "id": "hd-005",
  "name": "Round Jute Area Rug, 5x7",
  "category": "home_decor",
  "price": 96,
  "currency": "USD",
  "sku": "HP-HD-005",
  "in_stock": true,
  "description": "Natural jute area rug, hand-woven, 5x7 feet, suitable for living rooms and entryways."
}

Returns 404 if the id doesn't exist: { "error": "No product found with id \"zz-999\"." }

03POST /api/orders/create

Places a simulated order for a catalog product. Send product_id and quantity as a JSON body.

curl -X POST "https://houseproducts.odellblackmoniii.com/api/orders/create" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "sa-005", "quantity": 1}'

{
  "order_id": "ord-mulzd87qfys5",
  "status": "confirmed",
  "simulated": true,
  "product": { "id": "sa-005", "name": "Digital Air Fryer, 5.8-Quart", "price": 79.99 },
  "quantity": 1,
  "total_price": 79.99,
  "currency": "USD",
  "estimated_delivery": "2026-10-04",
  "created_at": "2026-09-29T01:11:13.622Z"
}

Returns 400 if product_id/quantity are missing, quantity isn't a positive integer, or the product is out of stock. Returns 404 if product_id doesn't exist.

04OpenAPI spec

Machine-readable spec: /openapi.yaml