Table of Contents
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
API Reference
WardrobeAI Curation Engine — Complete API Documentation
Base URL: http://localhost:3002
Health
GET /health
Check if the server is running.
Response 200:
{
"status": "ok",
"timestamp": "2026-05-02T20:00:00.000Z"
}
Profiles
GET /profiles
Retrieve all style profiles.
Response 200:
{
"profiles": [
{
"id": "profile_001",
"name": "Work Professional",
"description": "Office-appropriate attire for corporate environment",
"budget": 150,
"must_have_categories": "[\"tops\", \"bottoms\"]",
"preferred_styles": "[\"professional\", \"business formal\", \"business casual\", \"classic\"]",
"excluded_styles": "[\"bohemian\", \"edgy\", \"evening\"]",
"preferred_colors": "[\"black\", \"navy\", \"white\", \"gray\", \"beige\"]",
"max_price": 100,
"seasons": "[\"spring\", \"fall\"]",
"created_at": "2026-05-02 12:00:00"
}
]
}
GET /profiles/:id
Retrieve a single style profile by ID.
Example: GET /profiles/profile_001
404 Response:
{ "error": "Profile not found" }
GET /profiles/:id/matches
Get the top 20 matching inventory items for a profile, scored by the matching algorithm.
Example: GET /profiles/profile_001/matches
Response 200:
{
"matches": [
{
"score": 85,
"reasons": ["style match", "color match", "within budget"],
"item": { "id": "item_001", "name": "Classic White Blouse", "price": 49.99, ... },
"profile": { "id": "profile_001", ... }
}
]
}
POST /profiles/:id/box
Generate a curated box by selecting the best-matching items within budget using a greedy selection algorithm.
Optional body:
{ "budgetLimit": 200 }
Response 200:
{
"box": {
"profile": { "id": "profile_001", ... },
"items": [
{
"id": "item_001",
"name": "Classic White Blouse",
"price": 49.99,
"matchScore": 77,
"matchReasons": ["style match", "color match", "within budget"],
"image": "/images/white-blouse.jpg"
}
],
"totalPrice": 104.98,
"totalItems": 3,
"budgetUsedPercentage": 70
}
}
Inventory
GET /inventory
Retrieve all inventory items.
Response 200:
{
"items": [
{
"id": "item_001",
"name": "Classic White Blouse",
"price": 49.99,
"category": "tops",
"colors": "[\"white\", \"black\"]",
"styles": "[\"classic\", \"casual\", \"professional\"]",
"brand": "Classic Brands",
"description": "Versatile white blouse perfect for office or casual wear",
"image_path": "/images/white-blouse.jpg",
"created_at": "2026-05-02 12:00:00"
}
]
}
GET /inventory/:id
Retrieve a single inventory item by ID.
Example: GET /inventory/item_001
Boxes
GET /boxes/:userId
Get all curated boxes for a user, ordered by most recent first.
Response 200:
{
"boxes": [
{
"id": "box_1714672800000_abc123xyz",
"user_profile_id": "user_001",
"style_profile_id": "profile_001",
"items": "[{\"id\":\"item_001\",...}]",
"total_price": 104.98,
"created_at": "2026-05-02 12:00:00"
}
]
}
POST /boxes
Create a new curated box manually.
Request body:
{
"userId": "user_001",
"profileId": "profile_001",
"items": [{ "id": "item_001", "name": "Classic White Blouse", ... }],
"totalPrice": 104.98
}
Response 201:
{ "success": true, "boxId": "box_1714672800000_abc123xyz" }
Feedback
POST /feedback
Record feedback for items in a curated box.
Request body:
{
"boxId": "box_1714672800000_abc123xyz",
"feedback": [
{
"itemId": "item_001",
"rating": 5,
"kept": true,
"returned": false,
"notes": "Perfect fit, loved the fabric"
},
{
"itemId": "item_002",
"rating": 3,
"kept": false,
"returned": true,
"notes": "Didn't fit well"
}
]
}
Response 200:
{ "success": true, "count": 2 }
GET /feedback/analysis
Analyze all feedback data to identify item performance and compute improvement scores. Only items with 2+ feedback entries are included.
Response 200:
{
"improvements": [
{
"itemId": "item_001",
"avgRating": 4.5,
"keepRate": 80,
"returnRate": 20,
"improvementScore": 135
}
]
}
Improvement Score Formula:
improvementScore = (avgRating × 20) + (kept_count × 10) - (returned_count × 20)
Database
POST /seed
Seed the database with sample data: 20 inventory items and 5 style profiles.
Response 200:
{ "success": true, "message": "Database seeded successfully" }
Error Handling
| Status | Meaning |
|---|---|
| 200 | Success |
| 400 | Bad request (missing required fields: boxId, feedback) |
| 404 | Resource not found |
| 500 | Internal server error |
All errors return:
{ "error": "Description of what went wrong" }
Quick Start
# Start backend
cd wardrobe-ai/backend
npm start
# Server starts on port 3002
# Seed initial data
curl -X POST http://localhost:3002/seed
# Get profiles
curl http://localhost:3002/profiles
# Generate a box for profile_001
curl -X POST http://localhost:3002/profiles/profile_001/box
# Record feedback
curl -X POST http://localhost:3002/feedback \
-H "Content-Type: application/json" \
-d '{"boxId":"test","feedback":[{"itemId":"item_001","rating":5,"kept":true,"returned":false}]}'