Create a new catalog item

POST /api/catalog

Adds a new item to the catalog.

  • The attributes field structure is required and depends on the category. See schema description for details.
  • The item_vector field is optional. Send a 32-dimension array or omit/send null if no vector is available.
  • The id field should not be provided; it's generated by the server.
application/json

Body Required

Catalog item to add.

  • category string Required

    The category of the item. Determines the structure of 'attributes'.

    Values are tops, dresses, pants, outerwear, shoes, or accessories.

  • item_name string Required

    The name of the catalog item.

  • brand_id string Required

    Identifier for the item's brand.

  • item_url string(url) Required

    URL link to the item's product page.

  • price number(double) Required

    Price of the item.

  • item_img string(url) Required

    URL link to an image of the item.

  • attributes object Required

    Key-value pairs describing item-specific attributes. Required keys depend on the category field. See the main CatalogItem schema description for the expected structure per category.

    Additional properties are allowed.

  • item_vector array[number(float)] | null

    Optional 32-dimensional vector embedding for the item. Omit or send null if no vector is available.

    At least 32 but not more than 32 elements.

Responses

  • 201 application/json

    Item successfully created.

    Hide response attributes Show response attributes object
    • id integer(int64) Required

      Unique identifier for the catalog item (generated by the server).

    • category string Required

      The category of the item. Determines the structure of 'attributes'.

      Values are tops, dresses, pants, outerwear, shoes, or accessories.

    • item_name string Required

      The name of the catalog item.

    • brand_id string Required

      Identifier for the item's brand.

    • item_url string(url) Required

      URL link to the item's product page.

    • price number(double) Required

      Price of the item.

    • item_img string(url) Required

      URL link to an image of the item.

    • attributes object Required

      Key-value pairs describing item-specific attributes. Required keys depend on the category field.

      Category tops:

      {
  "size": "string",
  "fit": "string",
  "materials": ["string"],
  "pattern": "string",
  "colors": ["string"],
  "neckline": "string",
  "sleeve_length": "string",
  "closure_type": "string"
}

      Category dresses:

      {
  "size": "string",
  "fit": "string",
  "materials": ["string"],
  "pattern": "string",
  "colors": ["string"],
  "sleeve_length": "string",
  "shoulder_exposure": "string",
  "closure_type": "string",
  "back_exposure": "string",
  "neck_line": "string",
  "skirt_length": "string",
  "leg_cut": "string",
  "gender": "string",
  "seasonality": "string"
}

      Category pants:

      {
  "fit": "string",
  "materials": ["string"],
  "pattern": "string",
  "colors": ["string"],
  "length_to_knee": "string",
  "inseam": 0.0,
  "gender": "string",
  "seasonality": "string"
}

      Category outerwear:

      {
  "materials": ["string"],
  "pattern": "string",
  "colors": ["string"],
  "sleeve_length": "string",
  "gender": "string",
  "seasonality": "string"
}

      Category shoes:

      {
  "size": 0.0,
  "wide": "string",
  "colors": ["string"],
  "pattern": "string",
  "materials": ["string"],
  "shoe_height": "string",
  "heels": "string",
  "boots": "string",
  "gender": "string",
  "seasonality": "string"
}

      Category accessories:

      {
  "colors": ["string"],
  "worn": "string",
  "materials": ["string"],
  "closure_type": "string",
  "gender": "string",
  "seasonality": "string"
}

      Additional properties are allowed.

    • item_vector array[number(float)] | null

      Optional 32-dimensional vector embedding for the item. Will be null if not provided or stored.

      At least 32 but not more than 32 elements.
  • 400 application/json

    Bad Request (e.g., invalid JSON, validation error, missing required fields, unknown category, invalid vector dimensions if provided).

    Hide response attribute Show response attribute object
    • error string Required

      A message describing the error.
  • 500 application/json

    Internal Server Error

    Hide response attribute Show response attribute object
    • error string Required

      A message describing the error.
POST /api/catalog 
curl \
 --request POST 'http://localhost:8000/api/catalog' \
 --header "Content-Type: application/json" \
 --data '{"price":79.5,"brand_id":"brand_summer","category":"dresses","item_img":"https://example.com/images/dresses/floral-sundress.jpg","item_url":"https://example.com/products/dresses/floral-sundress","item_name":"Floral Print Sundress","attributes":{"fit":"A-Line","size":"S","colors":["Yellow","White","Green"],"gender":"Female","leg_cut":"N/A","pattern":"Floral","materials":["Rayon"],"neck_line":"V-Neck","seasonality":"Summer","closure_type":"Zipper","skirt_length":"Knee Length","back_exposure":"Low Back","sleeve_length":"Sleeveless","shoulder_exposure":"Spaghetti Straps"},"item_vector":[0.91,0.82,0.73,0.64,0.55,0.46,0.37,0.28,-0.19,-0.1,-0.21,-0.32,-0.43,-0.54,-0.65,-0.76,0.95,0.86,0.77,0.68,0.59,0.5,0.41,0.32,-0.23,-0.14,-0.25,-0.36,-0.47,-0.58,-0.69,-0.8]}'
Request examples 
{
  "price": 79.5,
  "brand_id": "brand_summer",
  "category": "dresses",
  "item_img": "https://example.com/images/dresses/floral-sundress.jpg",
  "item_url": "https://example.com/products/dresses/floral-sundress",
  "item_name": "Floral Print Sundress",
  "attributes": {
    "fit": "A-Line",
    "size": "S",
    "colors": [
      "Yellow",
      "White",
      "Green"
    ],
    "gender": "Female",
    "leg_cut": "N/A",
    "pattern": "Floral",
    "materials": [
      "Rayon"
    ],
    "neck_line": "V-Neck",
    "seasonality": "Summer",
    "closure_type": "Zipper",
    "skirt_length": "Knee Length",
    "back_exposure": "Low Back",
    "sleeve_length": "Sleeveless",
    "shoulder_exposure": "Spaghetti Straps"
  },
  "item_vector": [
    0.91,
    0.82,
    0.73,
    0.64,
    0.55,
    0.46,
    0.37,
    0.28,
    -0.19,
    -0.1,
    -0.21,
    -0.32,
    -0.43,
    -0.54,
    -0.65,
    -0.76,
    0.95,
    0.86,
    0.77,
    0.68,
    0.59,
    0.5,
    0.41,
    0.32,
    -0.23,
    -0.14,
    -0.25,
    -0.36,
    -0.47,
    -0.58,
    -0.69,
    -0.8
  ]
}
{
  "price\"": 24.99,
  "brand_id": "brand_basics",
  "category": "tops",
  "item_url": "https://example.com/products/tops/classic-crew-tee",
  "item_img\"": "https://example.com/images/tops/classic-crew-tee.jpg",
  "item_name": "Classic Crew Neck T-Shirt",
  "attributes\"": {
    "fit": "Regular",
    "size": "M",
    "colors": [
      "Heather Gray"
    ],
    "pattern": "Solid",
    "neckline": "Crew Neck",
    "materials": [
      "Cotton",
      "Polyester"
    ],
    "closure_type": "Pullover",
    "sleeve_length": "Short Sleeve"
  },
  "item_vector\"": null
}
{
  "price": 110.0,
  "brand_id": "brand_footwear",
  "category": "shoes",
  "item_img": "https://example.com/images/shoes/leather-sneakers-white.jpg",
  "item_url": "https://example.com/products/shoes/leather-sneakers-white",
  "item_name": "Classic Leather Sneakers",
  "attributes": {
    "size": 9.5,
    "wide": "Standard",
    "boots": "Not Boots",
    "heels": "Flat",
    "colors": [
      "White",
      "Blue accent"
    ],
    "gender": "Unisex",
    "pattern": "Solid with stripe",
    "materials": [
      "Leather Upper",
      "Rubber Sole"
    ],
    "seasonality": "All-Season",
    "shoe_height": "Low Top"
  }
}
Response examples (201) 
{
  "id": 42,
  "category": "tops",
  "item_name": "string",
  "brand_id": "string",
  "item_url": "string",
  "price": 42.0,
  "item_img": "string",
  "attributes": {},
  "item_vector": [
    42.0
  ]
}
Response examples (400) 
{
  "error": "string"
}
Response examples (500) 
{
  "error": "string"
}