Depict Listing (v2) API
The Listing (v2) API from Depict — 1 operation(s) for listing (v2).
OpenAPI Specification
openapi: 3.1.0
info:
title: Depict Lite Ab Test Listing (v2) API
version: 1.0.0
description: 'REST API behind Depict Lite, 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 require an Auth0-issued bearer token.'
servers:
- url: /api/lite
tags:
- name: Listing (v2)
paths:
/v2/product-listing:
post:
tags:
- Listing (v2)
summary: Get Products
operationId: Get_Products_v2_product_listing_post
security:
- APIKeyQuery: []
- APIKeyHeader: []
- APIKeyCookie: []
parameters:
- name: x-use-db-display-store
in: header
required: false
schema:
type: boolean
default: false
title: X-Use-Db-Display-Store
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProductListingRequestV2'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ProductListingResponseV2'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
SortMeta:
properties:
title:
type: string
title: Title
values:
items:
$ref: '#/components/schemas/SortingOrder'
type: array
title: Values
description: Selectable values
names:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Names
description: Names for orders (this is what you should display in the UI, not values)
additionalProperties: false
type: object
required:
- title
title: SortMeta
SearchFilter:
properties:
field:
type: string
title: Field
description: The field to filter by.
op:
type: string
enum:
- eq
- neq
- in
- nin
- leq
- geq
- inrange
title: Op
description: The operation used for filtering. The filtering should be read as `field op data`, for example `brand in ["Nike", "Adidas"]`.
data:
anyOf:
- type: string
enum:
- 'true'
- 'false'
- type: number
- type: integer
- type: string
- prefixItems:
- type: number
- type: number
type: array
maxItems: 2
minItems: 2
- prefixItems:
- type: integer
- type: integer
type: array
maxItems: 2
minItems: 2
- prefixItems:
- type: integer
- type: number
type: array
maxItems: 2
minItems: 2
- prefixItems:
- type: number
- type: integer
type: array
maxItems: 2
minItems: 2
- items:
anyOf:
- type: string
enum:
- 'true'
- 'false'
- type: number
- type: integer
- type: string
- prefixItems:
- type: number
- type: number
type: array
maxItems: 2
minItems: 2
- prefixItems:
- type: integer
- type: integer
type: array
maxItems: 2
minItems: 2
- prefixItems:
- type: integer
- type: number
type: array
maxItems: 2
minItems: 2
- prefixItems:
- type: number
- type: integer
type: array
maxItems: 2
minItems: 2
type: array
- items:
items:
type: string
type: array
type: array
- type: 'null'
title: Data
description: Data for the filter.
meta:
anyOf:
- oneOf:
- $ref: '#/components/schemas/RangeFilterMeta'
- $ref: '#/components/schemas/ValuesFilterMeta'
- $ref: '#/components/schemas/HierarchicalValuesFilterMeta'
discriminator:
propertyName: type
mapping:
checkbox: '#/components/schemas/ValuesFilterMeta'
checkbox-color: '#/components/schemas/ValuesFilterMeta'
checkbox-grid: '#/components/schemas/ValuesFilterMeta'
checkbox-hierarchical: '#/components/schemas/HierarchicalValuesFilterMeta'
radio: '#/components/schemas/ValuesFilterMeta'
range: '#/components/schemas/RangeFilterMeta'
- type: 'null'
title: Meta
description: Metadata about the filter that can be used for rendering. For example, this could contain the possible values to filter by and their counts in the results.
id:
anyOf:
- type: string
- type: 'null'
title: Id
description: ID of the filter. If multiple filters share the same ID, they should be grouped together in the UI.
additionalProperties: false
type: object
required:
- field
- op
title: SearchFilter
ECategoryType:
type: string
enum:
- TAG
- CATEGORY
- TENANT_CATEGORY
- TENANT_SECONDARY_CATEGORY
- CAMPAIGN
- BRAND
title: ECategoryType
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
RangeFilterMeta:
properties:
group_title:
anyOf:
- type: string
- type: 'null'
title: Group Title
description: Title of the group, where a group consists of all the filters that share an ID.
group_expanded:
anyOf:
- type: boolean
- type: 'null'
title: Group Expanded
description: Whether the filter group should be expanded by default or not.
type:
const: range
title: Type
min:
type: number
title: Min
description: The minimum value that can be selected in the range.
max:
type: number
title: Max
description: The maximum value that can be selected in the range.
unit:
anyOf:
- type: string
- type: 'null'
title: Unit
description: The unit of the range values.
currency:
anyOf:
- type: string
- type: 'null'
title: Currency
description: The currency of the range values.
additionalProperties: false
type: object
required:
- type
- min
- max
title: RangeFilterMeta
SortingOrder:
type: string
enum:
- asc
- desc
title: SortingOrder
ValuesFilterMeta:
properties:
group_title:
anyOf:
- type: string
- type: 'null'
title: Group Title
description: Title of the group, where a group consists of all the filters that share an ID.
group_expanded:
anyOf:
- type: boolean
- type: 'null'
title: Group Expanded
description: Whether the filter group should be expanded by default or not.
type:
type: string
enum:
- radio
- checkbox
- checkbox-grid
- checkbox-color
title: Type
description: Type of filter.
values:
items:
anyOf:
- type: string
enum:
- 'true'
- 'false'
- type: number
- type: integer
- type: string
- prefixItems:
- type: number
- type: number
type: array
maxItems: 2
minItems: 2
- prefixItems:
- type: integer
- type: integer
type: array
maxItems: 2
minItems: 2
- prefixItems:
- type: integer
- type: number
type: array
maxItems: 2
minItems: 2
- prefixItems:
- type: number
- type: integer
type: array
maxItems: 2
minItems: 2
type: array
title: Values
description: Selectable values
counts:
anyOf:
- items:
type: integer
type: array
- type: 'null'
title: Counts
description: Counts for values
names:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Names
description: Names for values. This is what should be displayed along with the UI item for the value.
additionalProperties: false
type: object
required:
- type
- values
title: ValuesFilterMeta
ProductListingRequestV2:
properties:
cursor:
anyOf:
- type: string
maxLength: 500
- type: 'null'
title: Cursor
description: Used for cursor-based pagination. Set it to the cursor from the last response. If not set, will return the first results.
limit:
anyOf:
- type: integer
maximum: 250
minimum: 1
- type: 'null'
title: Limit
description: Maximum number of results per response.
market:
type: string
title: Market
filters:
anyOf:
- items:
$ref: '#/components/schemas/SearchFilter'
type: array
- type: 'null'
title: Filters
description: List of filters to apply to the results.
sort:
anyOf:
- $ref: '#/components/schemas/SortModel-Input'
- type: 'null'
description: Specifies the sorting method. By default, the results are ordered by relevance. To find the possible values for this field, query the endpoint and look at the `sorts` field.
session_id:
anyOf:
- type: string
minLength: 1
- type: 'null'
title: Session Id
description: Session identifier
metadata:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Metadata
description: Metadata that can be used to modify the behaviour of the search.
tenant:
type: string
title: Tenant
locale:
anyOf:
- type: string
- type: 'null'
title: Locale
description: The locale to use for the search. If not set, the default locale will be used.
user_id:
anyOf:
- type: string
minLength: 1
- type: 'null'
title: User Id
description: User identifier
dsid:
anyOf:
- type: string
minLength: 1
- type: 'null'
title: Dsid
description: Populated for integrations performed by Depict.ai only. Depict.ai Session Id
query_id:
type: string
minLength: 1
title: Query Id
description: ID of the page to get products for. This is typically the slug, for example `hoodies-and-sweaters`.
type:
anyOf:
- $ref: '#/components/schemas/ProductListingType'
- type: 'null'
description: 'The type of query. If not set the endpoint will look up query id in the following type order: collections, categories.'
additionalProperties: false
type: object
required:
- market
- tenant
- query_id
title: ProductListingRequestV2
ProductListingType:
type: string
enum:
- category
- collection
- scollection
title: ProductListingType
SortModel-Output:
properties:
field:
type: string
title: Field
description: The field to sort by.
order:
allOf:
- $ref: '#/components/schemas/SortingOrder'
description: The order to sort by.
meta:
anyOf:
- $ref: '#/components/schemas/SortMeta'
- type: 'null'
description: 'Metadata about the sort that can be used for rendering. '
additionalProperties: false
type: object
required:
- field
- order
title: SortModel
PLPMetadata:
properties:
title:
type: string
title: Title
description:
anyOf:
- type: string
- type: 'null'
title: Description
replace_meta_tags:
type: boolean
title: Replace Meta Tags
description: Whether to replace the page meta tags, e.g., title and description, with the ones from the collection.
default: false
type: object
required:
- title
title: PLPMetadata
ProductListingResponseV2:
properties:
displays:
items:
type: object
type: array
title: Displays
description: The products to be shown on the product listing page.
n_hits:
type: integer
title: N Hits
description: Total number of results for this query. Not necessarily exact.
sorts:
anyOf:
- items:
$ref: '#/components/schemas/SortModel-Output'
type: array
- type: 'null'
title: Sorts
description: Available methods for sorting the response. Any element from this list can be sent as `sort` in subsequent requests.
filters:
anyOf:
- items:
$ref: '#/components/schemas/SearchFilter'
type: array
- type: 'null'
title: Filters
description: Available filters that can be used for filtering in the subsequent request.
product_listing_request_id:
type: string
title: Product Listing Request Id
cursor:
anyOf:
- type: string
maxLength: 500
- type: 'null'
title: Cursor
description: Cursor that can be used in the next request to get subsequent results. If this is not set, there are no more results.
breadcrumb:
anyOf:
- items:
$ref: '#/components/schemas/BaseCategoryDisplay'
type: array
- type: 'null'
title: Breadcrumb
description: Breadcrumb for the current page. Ordered from less to more specific, where the last element is the current page.
quick_links:
anyOf:
- items:
$ref: '#/components/schemas/BaseCategoryDisplay'
type: array
- type: 'null'
title: Quick Links
description: List of pages that can be used as quick links. Will return child pages if they exist, otherwise sibling pages.
metadata:
anyOf:
- $ref: '#/components/schemas/PLPMetadata'
- type: 'null'
description: Metadata about the PLP requested, for example Collection/Category title, description, etc.
additionalProperties: false
type: object
required:
- displays
- n_hits
- product_listing_request_id
title: ProductListingResponseV2
SortModel-Input:
properties:
field:
type: string
title: Field
description: The field to sort by.
order:
allOf:
- $ref: '#/components/schemas/SortingOrder'
description: The order to sort by.
meta:
anyOf:
- $ref: '#/components/schemas/SortMeta'
- type: 'null'
description: 'Metadata about the sort that can be used for rendering. '
additionalProperties: false
type: object
required:
- field
- order
title: SortModel
HierarchicalValuesFilterMeta:
properties:
group_title:
anyOf:
- type: string
- type: 'null'
title: Group Title
description: Title of the group, where a group consists of all the filters that share an ID.
group_expanded:
anyOf:
- type: boolean
- type: 'null'
title: Group Expanded
description: Whether the filter group should be expanded by default or not.
type:
const: checkbox-hierarchical
title: Type
values:
items:
items:
type: string
type: array
type: array
title: Values
description: Selectable hierarchical values
counts:
anyOf:
- items:
type: integer
type: array
- type: 'null'
title: Counts
description: Counts for values
names:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Names
description: Names for hierarchical values, this is what you should display in the UI (not values)
additionalProperties: false
type: object
required:
- type
- values
title: HierarchicalValuesFilterMeta
BaseCategoryDisplay:
properties:
category_id:
type: string
title: Category Id
description: Unique identifier of the category.
title:
type: string
title: Title
description: The title of the category
page_url:
anyOf:
- type: string
- type: 'null'
title: Page Url
description: The full URL to the category page
query_id:
anyOf:
- type: string
- type: 'null'
title: Query Id
description: Optionally a unique query ID for the category
uri:
anyOf:
- type: string
- type: 'null'
title: Uri
description: Optionally a unique URI for the category, for example men/shoes
category_type:
allOf:
- $ref: '#/components/schemas/ECategoryType'
description: The type of category, for example CAMPAIGN, TAG, or CATEGORY
default: CATEGORY
additionalProperties: false
type: object
required:
- category_id
- title
title: BaseCategoryDisplay
securitySchemes:
Auth0:
type: oauth2
flows:
authorizationCode:
scopes:
openid: OpenID Connect
profile: User profile
email: User email
authorizationUrl: https://depict.eu.auth0.com/oauth/authorize
tokenUrl: https://depict.eu.auth0.com/oauth/token
x-tokenName: id_token