> ## 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 an unsaved draft of a surface > As the GET preview, but composes the unsaved `surface` in the body (the upsert's shape) in place of the saved one, keyed to the saved surface's id and directives. Use it to show the effect of edits before saving. Read-only: nothing is written. ## OpenAPI ````yaml /api-reference/openapi/lite.json post /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: post: summary: Preview an unsaved draft of a surface description: >- As the GET preview, but composes the unsaved `surface` in the body (the upsert's shape) in place of the saved one, keyed to the saved surface's id and directives. Use it to show the effect of edits before saving. Read-only: nothing is written. operationId: recsSurfacePreviewDraft 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-`. required: true description: Lite merchant id, e.g. `shopify-`. 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 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RecsSurfacePreviewDraft' 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' '415': description: Content-Type is not application/json. 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: RecsSurfacePreviewDraft: type: object properties: surface: allOf: - $ref: '#/components/schemas/RecommendationSurfaceRequest' - description: >- The editor's unsaved surface (its `name` must be the path's); absent = preview the saved one. 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}`.' RecommendationSurfaceRequest: type: object properties: 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/PopularityParamsSchemaInput' filters: type: array items: $ref: '#/components/schemas/RecommendationFilterInput' default: [] description: Applied to this step's candidates only. limit: type: - integer - 'null' default: null description: >- Most slots this step may fill; null = as many as the surface limit leaves. required: - kind additionalProperties: false - type: object properties: kind: type: string enum: - most_viewed params: $ref: '#/components/schemas/PopularityParamsSchemaInput' filters: type: array items: $ref: '#/components/schemas/RecommendationFilterInput' default: [] description: Applied to this step's candidates only. limit: type: - integer - 'null' default: null description: >- Most slots this step may fill; null = as many as the surface limit leaves. required: - kind additionalProperties: false - type: object properties: kind: type: string enum: - bought_together params: type: object properties: {} default: {} additionalProperties: false filters: type: array items: $ref: '#/components/schemas/RecommendationFilterInput' default: [] description: Applied to this step's candidates only. limit: type: - integer - 'null' default: null description: >- Most slots this step may fill; null = as many as the surface limit leaves. required: - kind additionalProperties: false - type: object properties: kind: type: string enum: - viewed_together params: type: object properties: {} default: {} additionalProperties: false filters: type: array items: $ref: '#/components/schemas/RecommendationFilterInput' default: [] description: Applied to this step's candidates only. limit: type: - integer - 'null' default: null description: >- Most slots this step may fill; null = as many as the surface limit leaves. required: - kind additionalProperties: false - type: object properties: kind: type: string enum: - similar_products params: $ref: '#/components/schemas/SimilarProductsParamsSchemaInput' filters: type: array items: $ref: '#/components/schemas/RecommendationFilterInput' default: [] description: Applied to this step's candidates only. limit: type: - integer - 'null' default: null description: >- Most slots this step may fill; null = as many as the surface limit leaves. required: - kind additionalProperties: false - type: object properties: kind: type: string enum: - generative_cross_sell params: $ref: '#/components/schemas/GenerativeCrossSellParamsSchemaInput' filters: type: array items: $ref: '#/components/schemas/RecommendationFilterInput' default: [] description: Applied to this step's candidates only. limit: type: - integer - 'null' default: null description: >- Most slots this step may fill; null = as many as the surface limit leaves. required: - kind additionalProperties: false - type: object properties: kind: type: string enum: - new_arrivals params: type: object properties: {} default: {} additionalProperties: false filters: type: array items: $ref: '#/components/schemas/RecommendationFilterInput' default: [] description: Applied to this step's candidates only. limit: type: - integer - 'null' default: null description: >- Most slots this step may fill; null = as many as the surface limit leaves. required: - kind additionalProperties: false description: >- Recommenders in priority order: each fills the slots the ones before it left empty. filters: type: array items: $ref: '#/components/schemas/RecommendationFilterInput' default: [] description: Applied to every step's candidates. limit: type: integer default: 25 description: Slots the surface renders. excluded_product_ids: type: array items: type: string default: [] description: Products never recommended on this surface. required: - name - context - steps additionalProperties: false 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`. PopularityParamsSchemaInput: type: object properties: freshness_days: type: integer default: 30 candidate_pool: type: integer default: 10000 default: {} additionalProperties: false RecommendationFilterInput: oneOf: - $ref: '#/components/schemas/PriceFilterSchemaInput' - $ref: '#/components/schemas/CategoryFilterSchemaInput' - $ref: '#/components/schemas/TagFilterSchemaInput' - $ref: '#/components/schemas/OnSaleFilterSchemaInput' discriminator: propertyName: type mapping: price: $ref: '#/components/schemas/PriceFilterSchemaInput' category: $ref: '#/components/schemas/CategoryFilterSchemaInput' tag: $ref: '#/components/schemas/TagFilterSchemaInput' on_sale: $ref: '#/components/schemas/OnSaleFilterSchemaInput' SimilarProductsParamsSchemaInput: type: object properties: max_distance: type: number default: 0.5 default: {} additionalProperties: false GenerativeCrossSellParamsSchemaInput: type: object properties: max_distance: type: - number - 'null' default: null default: {} additionalProperties: false PriceFilterSchemaInput: type: object properties: type: type: string enum: - price min_fraction_of_median: type: - number - 'null' default: null max_fraction_of_median: type: - number - 'null' default: null required: - type additionalProperties: false description: 'Median-relative: 0.5 = half the anchor''s (or catalogue''s) median price.' CategoryFilterSchemaInput: 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 default: [] description: Collection ids; used by `any_of` only. required: - type - mode additionalProperties: false TagFilterSchemaInput: 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/TagSelectorSchemaInput' required: - type - mode - tags additionalProperties: false OnSaleFilterSchemaInput: type: object properties: type: type: string enum: - on_sale on_sale: type: boolean default: true description: true keeps only discounted products, false only full-price. required: - type additionalProperties: false TagSelectorSchemaInput: type: object properties: name: type: string description: The tag label. value: type: - string - 'null' default: null description: Pins `name:value`; null matches any tag with the label. required: - name additionalProperties: false 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. ````