> ## 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.

# Preview a saved surface

> Composes a saved surface right now from the current candidate pools, exactly as the storefront would for the given anchor and market, and returns the product ids per slot (pins included). A `product` or `category` surface needs `anchor_id`; an `any` surface must omit it. Read-only: nothing is written or recomputed.



## OpenAPI

````yaml /api-reference/openapi/lite.json get /recommendations/surfaces/{surface_name}/preview
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/{surface_name}/preview:
    get:
      summary: Preview a saved surface
      description: >-
        Composes a saved surface right now from the current candidate pools,
        exactly as the storefront would for the given anchor and market, and
        returns the product ids per slot (pins included). A `product` or
        `category` surface needs `anchor_id`; an `any` surface must omit it.
        Read-only: nothing is written or recomputed.
      operationId: recsSurfacePreview
      parameters:
        - schema:
            type: string
            pattern: ^[a-z0-9_-]+$
            description: The surface's URL-safe name.
          required: true
          description: The surface's URL-safe name.
          name: surface_name
          in: path
        - schema:
            type: string
            description: Lite merchant id, e.g. `shopify-<shop id>`.
          required: true
          description: Lite merchant id, e.g. `shopify-<shop id>`.
          name: merchant_id
          in: query
        - schema:
            type: string
            description: Product or collection id for an anchored surface; empty = absent.
          required: false
          description: Product or collection id for an anchored surface; empty = absent.
          name: anchor_id
          in: query
        - schema:
            type: string
            description: Market to compose for; absent or empty = the default market.
          required: false
          description: Market to compose for; absent or empty = the default market.
          name: market_id
          in: query
      responses:
        '200':
          description: The composed slots, dense from position 0, pins included.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecsSurfacePreview'
        '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, or no such surface or
            recommendations config.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detail'
        '422':
          description: >-
            The surface cannot be previewed as asked (anchor missing or not
            allowed, unknown market, draft name mismatch).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detail'
        '500':
          description: Internal error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detail'
        '502':
          description: The candidate pools could not be read.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detail'
components:
  schemas:
    RecsSurfacePreview:
      type: object
      properties:
        surface_id:
          type: string
        context:
          type: string
          enum:
            - product
            - category
            - any
        market_id:
          type: string
        available_markets:
          type: array
          items:
            type: string
        generated_at:
          type: string
        slots:
          type: array
          items:
            type: object
            properties:
              position:
                type: integer
              product_id:
                type: string
            required:
              - position
              - product_id
      required:
        - surface_id
        - context
        - market_id
        - available_markets
        - generated_at
        - slots
    Detail:
      type: object
      properties:
        detail:
          type: string
      required:
        - detail
      description: 'Every 4xx/5xx body: `{detail}`.'
  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.

````