> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# return top curated recommendations for a user

> Returns curated recommendations for a user profile without targeting a specific garment.

This is the v2 equivalent of `/items/top`. It uses the same service objects and retry/fallback logic.

No `user` object is returned.


## OpenAPI

````json GET /v2/items/top
{
  "openapi": "3.0.4",
  "info": {
    "title": "Mapp Fashion API",
    "description": "Mapp Fashion recommendation API.\n\n**Host:** there is no shared API host. A dedicated host is configured per partner and supplied during onboarding. All paths below are relative to that host.\n\nTwo versions are available in parallel. **v1** (`/api/...`) covers the established endpoints and is fully maintained, with no deprecation planned. **v2** (`/api/v2/...`) standardizes the inputs and provides one endpoint per recommendation type. New integrations should use v2 wherever a v2 endpoint exists. See Recommendation Strategy for which endpoint to use when.\n",
    "version": "13"
  },
  "servers": [
    {
      "url": "/api"
    }
  ],
  "security": [
    {
      "api_key": []
    },
    {
      "api_key": [],
      "user_token": []
    }
  ],
  "tags": [
    {
      "name": "Items",
      "description": "Operations for retrieving recommendations or items related to one or more seed items"
    },
    {
      "name": "Items (v2)",
      "description": "v2: one endpoint per recommendation type, identifiers passed as parameters"
    },
    {
      "name": "Recommendations",
      "description": "Operations about recommendations"
    },
    {
      "name": "Recommendations (v2)",
      "description": "v2: facetted recommendations in the v2 response format"
    },
    {
      "name": "Authorization",
      "description": "Operations for obtaining or refreshing JWTs"
    }
  ],
  "paths": {
    "/v2/items/top": {
      "get": {
        "tags": [
          "Items (v2)"
        ],
        "summary": "return top curated recommendations for a user",
        "description": "Returns curated recommendations for a user profile without targeting a specific garment.\n\nThis is the v2 equivalent of `/items/top`. It uses the same service objects and retry/fallback logic.\n\nNo `user` object is returned.\n",
        "operationId": "getV2ItemsTop",
        "parameters": [
          {
            "name": "department",
            "in": "query",
            "description": "The department to which the items will belong\n",
            "schema": {
              "enum": [
                "female",
                "male",
                "girls",
                "boys",
                "unisex"
              ],
              "type": "string",
              "default": "female"
            }
          },
          {
            "name": "excluded_ids",
            "in": "query",
            "description": "List of garment identifiers to be excluded from the recommendations Pass a comma separated list, for example `excluded_ids=A,B`. Bracketed array syntax is not accepted.\n",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          {
            "name": "max_items",
            "in": "query",
            "description": "The maximum number of items to return. Six items are returned when this parameter is not set\n",
            "schema": {
              "maximum": 20,
              "minimum": 1,
              "type": "integer",
              "format": "int32",
              "default": 6
            }
          },
          {
            "name": "max_reduced_by",
            "in": "query",
            "description": "The maximum price reduction (in percent) of any returned item\n",
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "garment_format",
            "in": "query",
            "description": "The desired response format.\n\nIf `simple`, only basic garment identifiers are returned. If `detailed`, more comprehensive garment metadata (name, description, price etc.) is included.\n\n`simple` is equivalent to the v1 value `retailer_ids`. The v1 value `document` is not available in v2.\n\nWith `detailed`, garment attributes are returned in `garment_data` as `GarmentDetail` objects. The v1 `fields` parameter has no v2 equivalent: the set of attributes is fixed and depends on the endpoint and your product data.\n",
            "schema": {
              "enum": [
                "simple",
                "detailed"
              ],
              "type": "string",
              "default": "simple"
            }
          },
          {
            "name": "locale",
            "in": "query",
            "description": "A locale parameter describing what stock information to use and what language to return text in (if applicable). This parameter will only function if the corresponding information is in your product data & processed accordingly. If stock locale and UI language are not the same, specify the language parameter in addition to this one.\n",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "language",
            "in": "query",
            "description": "Allows you to specify a locale used for product attributes such as product name that should be localized using a different locale to price & stock information. This parameter will only function if the corresponding information is in your product data & processed accordingly.\n",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pretty",
            "in": "query",
            "description": "If true, pretty print JSON output. This increases response size and should usually be off in production environments\n",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_fashion_ids",
            "in": "query",
            "description": "Controls whether Mapp Fashion garment ids (`raw_garment_id`) are included for the returned items.\n\nNote that this defaults to `false`, whereas the v1 equivalent defaults to `true`.\n",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Information about the curated recommendations",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V2TopRecommendationsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing client_id, or one or more parameter values are invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/InvalidJwt"
          },
          "404": {
            "description": "No recommender is available for this partner",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "V2TopRecommendationsResponse": {
        "required": [
          "event_id",
          "top_items",
          "garment_data",
          "available_skus"
        ],
        "type": "object",
        "properties": {
          "event_id": {
            "type": "string",
            "description": "An event id. Use it when posting events relating to this dataset"
          },
          "currency": {
            "type": "string",
            "description": "The currency the prices in this response are expressed in, resolved from the requested locale (the default currency if no locale is given). Null if your product data contains no currency",
            "nullable": true,
            "example": "GBP"
          },
          "garment_data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GarmentDetail"
            },
            "description": "Attributes of the garments in the response. Empty unless `garment_format=detailed`"
          },
          "available_skus": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AvailableSkus"
            },
            "description": "The variant SKUs of the recommended items that are still in stock, one entry per item. An empty array when none are known.\n\nOnly reliable if the variant IDs are maintained in the Product Catalog and the products have their real product images from the first import on. Products imported with placeholder images or dummy URLs can receive SKUs of other products."
          },
          "top_items": {
            "$ref": "#/components/schemas/TopItems"
          }
        },
        "description": "The response of `/api/v2/items/top`.\n\nNo `user` object is returned.\n",
        "example": {
          "event_id": "6a959e5e159ce757e62171df",
          "currency": "GBP",
          "garment_data": [],
          "top_items": {
            "content_id": "6aaa520ce30e2296b040af43",
            "items": [
              {
                "garment_id": "TQ11013OLIVE",
                "ancillary_product_code": "TQ11013"
              },
              {
                "garment_id": "TR11011CAMEL",
                "ancillary_product_code": "TR11011"
              }
            ]
          },
          "available_skus": [
            {
              "garment_id": "TQ11013OLIVE",
              "skus": [
                "TQ11013OLIVE-S",
                "TQ11013OLIVE-M"
              ]
            }
          ]
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string",
                "description": "A human readable error message"
              }
            }
          }
        },
        "description": "Generic error object"
      },
      "GarmentDetail": {
        "required": [
          "id",
          "product_code"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "The internal Mapp Fashion id for the garment",
            "format": "int32"
          },
          "product_code": {
            "type": "string",
            "description": "The product code from your product data"
          },
          "product_id": {
            "type": "string",
            "description": "The product level identifier the product code belongs to (Product ID in the Product Catalog)"
          },
          "partner": {
            "type": "string",
            "description": "The partner identifier"
          },
          "retailer": {
            "type": "string",
            "description": "The retailer name"
          },
          "brand_name": {
            "type": "string",
            "description": "The brand name"
          },
          "name": {
            "type": "string",
            "description": "The product name"
          },
          "price": {
            "type": "string",
            "description": "The current price as it appears in your product data. Formatting follows your product data and does not necessarily include a currency"
          },
          "old_price": {
            "type": "string",
            "description": "The previous price as it appears in your product data. Empty if the garment is not reduced"
          },
          "rating": {
            "type": "number",
            "description": "Product rating. May be null if your product data does not provide one",
            "nullable": true
          },
          "url": {
            "type": "string",
            "description": "The URL of the product detail page"
          },
          "garment_category_id": {
            "type": "integer",
            "description": "The category id for the product",
            "format": "int32"
          },
          "garment_category_name": {
            "type": "string",
            "description": "The category name for the product"
          },
          "department": {
            "type": "string",
            "description": "The garment department"
          },
          "feed_image_urls": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "All image URLs present in your product data"
          },
          "image_url": {
            "type": "string",
            "description": "Mapp Fashion hosted image for the garment"
          },
          "thumbnail_image_url": {
            "type": "string",
            "description": "Mapp Fashion hosted thumbnail for the garment"
          },
          "best_model_image": {
            "type": "string",
            "description": "The product image judged to be the best model shot. May be empty"
          },
          "best_product_image": {
            "type": "string",
            "description": "The product image judged to be the best product shot. May be null"
          },
          "why": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Human readable reasons for the recommendation. Only populated if the profile has shape data"
          },
          "has_outfits": {
            "type": "boolean",
            "description": "Whether outfits can be generated for the garment"
          },
          "garment_status": {
            "type": "string",
            "description": "The stock status of the garment"
          }
        },
        "description": "An entry in `garment_data`, returned when `garment_format=detailed`.\n\nNote that this object is not the same shape as `Garment` (used by the v1 recommendations endpoints): it carries the product and media attributes of the garment and identifies it via `id` and `product_code` rather than `garment_id`.\n\nThe set of attributes present depends on the endpoint and on what your product data contains, so individual attributes may be absent, empty or null. The v1 `fields` parameter has no v2 equivalent.\n\nDo not rely on the order of this array. It does not necessarily match the order of the recommendations, which is authoritative for display.\n",
        "example": {
          "id": 5251640,
          "product_code": "TS30165CHARCOALHB",
          "product_id": "TS30165",
          "partner": "examplepartner",
          "retailer": "ExamplePartner",
          "brand_name": "Example Brand",
          "name": "Men's Raglan Sleeve British Tweed Coat",
          "price": "345.00",
          "old_price": "",
          "url": "https://www.example.com/raglan-sleeve-tweed-coat-ts30165charcoalhb/",
          "garment_category_id": 84,
          "garment_category_name": "Outerwear",
          "department": "male",
          "feed_image_urls": [
            "https://media.example.com/products/TS30165CHARCOALHB.jpg"
          ],
          "image_url": "https://cdn.example.net/garment-5251640-9331038.jpg",
          "thumbnail_image_url": "https://cdn.example.net/thumbnail-5251640-9331038.jpg",
          "why": [],
          "has_outfits": true,
          "garment_status": "in stock"
        }
      },
      "AvailableSkus": {
        "required": [
          "garment_id",
          "skus"
        ],
        "type": "object",
        "properties": {
          "garment_id": {
            "type": "string",
            "description": "The item the SKUs belong to, as returned in `garment_id`"
          },
          "skus": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The variant SKUs of the item that are still in stock"
          }
        },
        "description": "The in-stock variant SKUs of one recommended item.",
        "example": {
          "garment_id": "TS30165CHARCOALHB",
          "skus": [
            "TS30165CHARCOALHB-S",
            "TS30165CHARCOALHB-M"
          ]
        }
      },
      "TopItems": {
        "required": [
          "content_id",
          "items"
        ],
        "type": "object",
        "properties": {
          "content_id": {
            "type": "string",
            "description": "An opaque identifier identifying this section of the response. This should be used when posting posting events relating to an item in this outfit.",
            "example": "5a621005c2c9adc12e1192b7"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BareGarment"
            },
            "description": "The curated items"
          }
        }
      },
      "BareGarment": {
        "required": [
          "garment_id"
        ],
        "type": "object",
        "properties": {
          "garment_id": {
            "type": "string",
            "description": "The item identifier. In v2, it uses the same identifier type as the request (`identifier_type`), by default the product code. In v1, the type of identifier depends on the request's `garment_format`",
            "example": "ABC-123"
          },
          "raw_garment_id": {
            "type": "integer",
            "description": "The internal Mapp Fashion id for the garment. This may be omitted depending on `garment_format`",
            "format": "int32",
            "example": 123456
          },
          "product_id": {
            "type": "string",
            "description": "The product level identifier the item belongs to (Product ID in the Product Catalog), grouping all its colors and sizes. Omitted if your product data contains no Product ID",
            "example": "TS30165"
          },
          "ancillary_product_code": {
            "type": "string",
            "description": "An alternative identifier to identify the product, hidden when not provided in your product data",
            "example": "A1B2C3"
          }
        }
      }
    },
    "responses": {
      "InvalidJwt": {
        "description": "Invalid JWT: a user token was supplied but could not be verified. Requests without a user token are not affected - they return non-personalized results",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ServerError": {
        "description": "An internal error occurred. Retry the request. If the issue persists, contact Technical Support",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "The request was queued for too long because of high load. Retry the request later",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "api_key": {
        "type": "apiKey",
        "name": "x-api-key",
        "in": "header"
      },
      "user_token": {
        "type": "apiKey",
        "description": "The JWT for the user. Optional: requests without a user token return non-personalized results. The header name is unchanged for backwards compatibility.",
        "name": "x-dressipi-jwt",
        "in": "header"
      }
    }
  }
}
````