> ## Documentation Index > Fetch the complete documentation index at: https://docs.depict.ai/llms.txt > Use this file to discover all available pages before exploring further. # List the merchant's recommendation surfaces > Returns every recommendation surface the merchant has configured, as an object keyed by surface name in creation order. Call it to discover which surfaces exist (and their ids) before reading, editing, previewing or pinning one. Read-only; a merchant with recommendations not set up gets `{}`. ## OpenAPI ````yaml /api-reference/openapi/lite.json get /recommendations/surfaces openapi: 3.1.0 info: title: Search & Merchandising API version: 1.0.0 description: >- REST API behind Depict: Search & Merchandising, the native Shopify app: onboarding, collections, boost & bury, dashboards, A/B testing and multi-store management. Endpoints are served under the /api/lite prefix and are authenticated with the Shopify session token that App Bridge issues to the embedded app. servers: - url: /api/lite security: - ShopifySessionToken: [] paths: /recommendations/surfaces: get: summary: List the merchant's recommendation surfaces description: >- Returns every recommendation surface the merchant has configured, as an object keyed by surface name in creation order. Call it to discover which surfaces exist (and their ids) before reading, editing, previewing or pinning one. Read-only; a merchant with recommendations not set up gets `{}`. operationId: recsSurfacesList parameters: - schema: type: string description: Lite merchant id, e.g. `shopify-`. required: true description: Lite merchant id, e.g. `shopify-`. name: merchant_id in: query responses: '200': description: Every surface keyed by name; `{}` when nothing is configured. content: application/json: schema: $ref: '#/components/schemas/RecommendationSurfacesByName' '400': description: >- The query, path or body failed the schema; `detail` carries zod's messages. content: application/json: schema: $ref: '#/components/schemas/Detail' '401': description: Not authenticated. content: application/json: schema: $ref: '#/components/schemas/Detail' '403': description: Authenticated, but this identity may not call the API. content: application/json: schema: $ref: '#/components/schemas/Detail' '404': description: Merchant not found for this caller. content: application/json: schema: $ref: '#/components/schemas/Detail' '500': description: Internal error. content: application/json: schema: $ref: '#/components/schemas/Detail' components: schemas: RecommendationSurfacesByName: type: object additionalProperties: $ref: '#/components/schemas/RecommendationSurfaceSchema' description: Every surface keyed by name, in creation order. Detail: type: object properties: detail: type: string required: - detail description: 'Every 4xx/5xx body: `{detail}`.' RecommendationSurfaceSchema: type: object properties: id: type: string description: >- Stable uuid; kept across upserts. Pins, metrics and compose address the surface by it. name: type: string pattern: ^[a-z0-9_-]+$ description: >- URL-safe (`[a-z0-9_-]+`); also the storefront metaobject handle the theme block references. context: $ref: '#/components/schemas/SurfaceContext' steps: type: array items: oneOf: - type: object properties: kind: type: string enum: - best_sellers params: $ref: '#/components/schemas/PopularityParamsSchema' filters: type: array items: $ref: '#/components/schemas/RecommendationFilter' description: Applied to this step's candidates only. limit: type: - integer - 'null' description: >- Most slots this step may fill; null = as many as the surface limit leaves. seed: $ref: '#/components/schemas/RecommendationStepSeed' required: - kind - params - filters - limit - type: object properties: kind: type: string enum: - most_viewed params: $ref: '#/components/schemas/PopularityParamsSchema' filters: type: array items: $ref: '#/components/schemas/RecommendationFilter' description: Applied to this step's candidates only. limit: type: - integer - 'null' description: >- Most slots this step may fill; null = as many as the surface limit leaves. seed: $ref: '#/components/schemas/RecommendationStepSeed' required: - kind - params - filters - limit - type: object properties: kind: type: string enum: - bought_together params: type: object properties: {} filters: type: array items: $ref: '#/components/schemas/RecommendationFilter' description: Applied to this step's candidates only. limit: type: - integer - 'null' description: >- Most slots this step may fill; null = as many as the surface limit leaves. seed: $ref: '#/components/schemas/RecommendationStepSeed' required: - kind - params - filters - limit - type: object properties: kind: type: string enum: - viewed_together params: type: object properties: {} filters: type: array items: $ref: '#/components/schemas/RecommendationFilter' description: Applied to this step's candidates only. limit: type: - integer - 'null' description: >- Most slots this step may fill; null = as many as the surface limit leaves. seed: $ref: '#/components/schemas/RecommendationStepSeed' required: - kind - params - filters - limit - type: object properties: kind: type: string enum: - similar_products params: $ref: '#/components/schemas/SimilarProductsParamsSchema' filters: type: array items: $ref: '#/components/schemas/RecommendationFilter' description: Applied to this step's candidates only. limit: type: - integer - 'null' description: >- Most slots this step may fill; null = as many as the surface limit leaves. seed: $ref: '#/components/schemas/RecommendationStepSeed' required: - kind - params - filters - limit - type: object properties: kind: type: string enum: - generative_cross_sell params: $ref: '#/components/schemas/GenerativeCrossSellParamsSchema' filters: type: array items: $ref: '#/components/schemas/RecommendationFilter' description: Applied to this step's candidates only. limit: type: - integer - 'null' description: >- Most slots this step may fill; null = as many as the surface limit leaves. seed: $ref: '#/components/schemas/RecommendationStepSeed' required: - kind - params - filters - limit - type: object properties: kind: type: string enum: - new_arrivals params: type: object properties: {} filters: type: array items: $ref: '#/components/schemas/RecommendationFilter' description: Applied to this step's candidates only. limit: type: - integer - 'null' description: >- Most slots this step may fill; null = as many as the surface limit leaves. seed: $ref: '#/components/schemas/RecommendationStepSeed' required: - kind - params - filters - limit - type: object properties: kind: type: string enum: - recently_viewed params: type: object properties: {} filters: type: array items: $ref: '#/components/schemas/RecommendationFilter' description: Applied to this step's candidates only. limit: type: - integer - 'null' description: >- Most slots this step may fill; null = as many as the surface limit leaves. seed: $ref: '#/components/schemas/RecommendationStepSeed' required: - kind - params - filters - limit description: >- Recommenders in priority order: each fills the slots the ones before it left empty. filters: type: array items: $ref: '#/components/schemas/RecommendationFilter' description: Applied to every step's candidates. limit: type: integer description: Slots the surface renders. excluded_product_ids: type: array items: type: string description: Products never recommended on this surface. pin_mode: type: string enum: - insert - override looks: type: string enum: - none - first - only custom_rules: type: array items: {} only_show_pinned: type: boolean avoid_surfaces: type: array items: type: string required: - id - name - context - steps - filters - limit - excluded_product_ids - pin_mode - looks - custom_rules - only_show_pinned - avoid_surfaces description: >- A saved surface. `pin_mode`, `looks`, `custom_rules`, `only_show_pinned` and `avoid_surfaces` are ops-only serving directives, as are a step's `seed` and the `recently_viewed` kind: read-only here, an upsert keeps the directives. SurfaceContext: type: string enum: - product - category - any description: >- Where the surface renders: `product` (a product page, anchored on that product), `category` (a collection page, anchored on the collection) or `any` (unanchored). Per-product recommenders need `product`. PopularityParamsSchema: type: object properties: freshness_days: type: integer candidate_pool: type: integer required: - freshness_days - candidate_pool RecommendationFilter: oneOf: - $ref: '#/components/schemas/PriceFilterSchema' - $ref: '#/components/schemas/CategoryFilterSchema' - $ref: '#/components/schemas/TagFilterSchema' - $ref: '#/components/schemas/OnSaleFilterSchema' discriminator: propertyName: type mapping: price: $ref: '#/components/schemas/PriceFilterSchema' category: $ref: '#/components/schemas/CategoryFilterSchema' tag: $ref: '#/components/schemas/TagFilterSchema' on_sale: $ref: '#/components/schemas/OnSaleFilterSchema' RecommendationStepSeed: type: object properties: source: type: string enum: - anchor - history_viewed - history_cart max_seeds: type: integer required: - source description: 'Ops-only: what seeds a per-product step.' SimilarProductsParamsSchema: type: object properties: max_distance: type: number required: - max_distance GenerativeCrossSellParamsSchema: type: object properties: max_distance: type: - number - 'null' required: - max_distance PriceFilterSchema: type: object properties: type: type: string enum: - price min_fraction_of_median: type: - number - 'null' max_fraction_of_median: type: - number - 'null' required: - type - min_fraction_of_median - max_fraction_of_median description: 'Median-relative: 0.5 = half the anchor''s (or catalogue''s) median price.' CategoryFilterSchema: type: object properties: type: type: string enum: - category mode: type: string enum: - same_as_anchor - other_than_anchor - any_of category_ids: type: array items: type: string description: Collection ids; used by `any_of` only. required: - type - mode - category_ids TagFilterSchema: type: object properties: type: type: string enum: - tag mode: type: string enum: - same_as_anchor - other_than_anchor - any_of - none_of tags: type: array items: $ref: '#/components/schemas/TagSelectorSchema' required: - type - mode - tags OnSaleFilterSchema: type: object properties: type: type: string enum: - on_sale on_sale: type: boolean description: true keeps only discounted products, false only full-price. required: - type - on_sale TagSelectorSchema: type: object properties: name: type: string description: The tag label. value: type: - string - 'null' description: Pins `name:value`; null matches any tag with the label. required: - name - value securitySchemes: ShopifySessionToken: type: http scheme: bearer bearerFormat: JWT description: >- Shopify App Bridge session token of the embedded Depict: Search & Merchandising app. The shop in the token determines the merchant; merchant_id parameters must belong to that shop. ````