openapi: 3.1.0 info: title: Depict Lite Ab Test Search (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: Search (v2) paths: /v2/search/results: post: tags: - Search (v2) summary: Get Results description: "Used to get search results that match the given query. Has support for filtering and\nsorting.\n\nExample response:\n
\n{\n   \"n_hits\": 1,\n   \"displays\": [\n     {\n         \"product_id\": \"foobar\",\n         \"title\": \"Foobar\"\n     }\n   ],\n   \"sorts\": [\n     {\n       \"field\": \"_relevance\",\n       \"order\": \"desc\",\n       \"meta\": {\n         \"title\": \"Relevance\",\n         \"values\": [\n           \"desc\"\n         ],\n         \"names\": [\n           \"Relevance\"\n         ]\n       }\n     },\n     {\n       \"field\": \"title\",\n       \"order\": \"asc\",\n       \"meta\": {\n         \"title\": \"Title\",\n         \"values\": [\n           \"asc\",\n           \"desc\"\n         ],\n         \"names\": [\n           \"A-Z\",\n           \"Z-A\"\n         ]\n       }\n     }\n   ],\n   \"filters\": [\n     {\n       \"field\": \"sale_price\",\n       \"op\": \"inrange\",\n       \"data\": [\n         0,\n         2500\n       ],\n       \"meta\": {\n         \"group_title\": \"Price\",\n         \"type\": \"range\",\n         \"min\": 0,\n         \"max\": 2500,\n         \"currency\": \"EUR\"\n       },\n       \"id\": \"price0\"\n     },\n     {\n       \"field\": \"color_name\",\n       \"op\": \"in\",\n       \"meta\": {\n         \"group_title\": \"Color\",\n         \"type\": \"checkbox\",\n         \"values\": [\n           \"Blue\",\n           \"Black\",\n           \"Brown\"\n         ]\n       },\n       \"id\": \"colors1\"\n     }\n   ],\n   \"search_request_id\": \"1a278f4a-16eb-4d95-a002-88bd305493d4\",\n   \"cursor\": \"eyJjIjogMSwgInIiOiAwfQ==\"\n }\n 
\n\n Example request body for applying a filter:\n
\n {\n    \"tenant\": \"foobar\"\n    \"market\": \"en\",\n    \"limit\": 20,\n    \"query\": \"hoodie\",\n    \"filters\": [\n        {\n            \"field\": \"color_name\",\n            \"op\": \"in\",\n            \"data\": [\"Blue\"]\n        }\n    ]\n }\n 
" operationId: Get_results_v2_search_results_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/SearchRequestV2' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v2/search/suggestions: get: tags: - Search (v2) summary: Get Suggestions description: "Returns suggestions for a given query. Call this while the user is typing to help\nthe user find what they're looking for. The suggestions are of two types:\n- suggestions for search queries that are related to the current query\n- suggestions for categories that are related to the current query\n\nExample response:\n
\n{\n  \"suggestions_request_id\": \"c6fa5efd-1bde-43a8-9ac4-434605f53024\",\n  \"suggestions\": [\n    {\n      \"type\": \"query\",\n      \"title\": \"red hat\",\n      \"suggestions_result_id\": \"60c54958-8f2d-4ffd-a343-d316e79593b8\"\n    },\n    {\n      \"category_id\": \"sweaters-hoodies\",\n      \"title\": \"Sweaters & Hoodies\",\n      \"page_url\": \"https://foobar.com/sweaters-hoodies\",\n      \"type\": \"category\",\n      \"suggestions_result_id\": \"b11ee4a9-0d95-4559-b1fa-76479ca3e3ea\"\n    }\n  ]\n}\n
" operationId: Get_suggestions_v2_search_suggestions_get security: - APIKeyQuery: [] - APIKeyHeader: [] - APIKeyCookie: [] parameters: - name: tenant in: query required: true schema: type: string title: Tenant - name: market in: query required: true schema: type: string title: Market - name: locale in: query required: false schema: anyOf: - type: string - type: 'null' title: Locale - name: query in: query required: false schema: anyOf: - type: string - type: 'null' title: Query - name: user_id in: query required: false schema: anyOf: - type: string minLength: 1 - type: 'null' title: User Id - name: session_id in: query required: false schema: anyOf: - type: string minLength: 1 - type: 'null' title: Session Id - name: dsid in: query required: false schema: anyOf: - type: string minLength: 1 - type: 'null' title: Dsid - name: metadata in: query required: false schema: anyOf: - {} - type: 'null' title: Metadata responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SearchSuggestionsResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v2/search/related: post: tags: - Search (v2) summary: Get Related Recommendations description: 'Returns recommendations for products related to the search query. Note that this endpoint takes the same request body as the `/v2/search/results` endpoint, excluding the pagination parameters. It should be called once the user has exhausted the search results for their query and the recommended products are typically shown below the search results.' operationId: Get_related_recommendations_v2_search_related_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/BaseSearchRequestV2' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/RecommendResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v2/search/content: get: tags: - Search (v2) summary: Search Through Text Content description: '(EXPERIMENTAL) Search through text content. The indexed text content is configurable. Example response: WIP ' operationId: Search_through_text_content_v2_search_content_get security: - APIKeyQuery: [] - APIKeyHeader: [] - APIKeyCookie: [] parameters: - name: tenant in: query required: true schema: type: string title: Tenant - name: market in: query required: true schema: type: string title: Market - name: locale in: query required: false schema: anyOf: - type: string - type: 'null' title: Locale - name: query in: query required: false schema: anyOf: - type: string - type: 'null' title: Query - name: user_id in: query required: false schema: anyOf: - type: string minLength: 1 - type: 'null' title: User Id - name: session_id in: query required: false schema: anyOf: - type: string minLength: 1 - type: 'null' title: Session Id - name: dsid in: query required: false schema: anyOf: - type: string minLength: 1 - type: 'null' title: Dsid responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ContentSearchResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: ECategoryType: type: string enum: - TAG - CATEGORY - TENANT_CATEGORY - TENANT_SECONDARY_CATEGORY - CAMPAIGN - BRAND title: ECategoryType RecommendResponse: properties: displays: items: type: object type: array title: Displays error: anyOf: - type: string - type: 'null' title: Error variant: anyOf: - type: integer - type: 'null' title: Variant experiment_id: anyOf: - type: string - type: 'null' title: Experiment Id additionalProperties: false type: object required: - displays title: RecommendResponse 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 ContentSearchResponse: properties: content_request_id: type: string title: Content Request Id links: items: $ref: '#/components/schemas/ContentLink' type: array title: Links description: List of links to content pages that match the search query. additionalProperties: false type: object required: - content_request_id - links title: ContentSearchResponse 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 ContentLink: properties: type: const: content_link title: Type default: content_link title: type: string title: Title description: Title for the content page description: anyOf: - type: string - type: 'null' title: Description description: Short human-readable description for the content page image_url: anyOf: - type: string - type: 'null' title: Image Url description: URL for the content page image page_url: type: string title: Page Url description: URL for the content page highlights: items: $ref: '#/components/schemas/TypesenseHighlights' type: array title: Highlights description: Highlights that show why the search query matched this content page additionalProperties: false type: object required: - title - description - page_url title: ContentLink 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 TypesenseHighlights: properties: field: type: string title: Field snippet: type: string title: Snippet matched_tokens: items: type: string type: array title: Matched Tokens additionalProperties: false type: object required: - field - snippet - matched_tokens title: TypesenseHighlights 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 SearchResponse: properties: 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. search_request_id: type: string title: Search 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. content_search_links: items: $ref: '#/components/schemas/ContentLink' type: array title: Content Search Links description: List of links to content pages that match the search query. displays: items: type: object type: array title: Displays description: The search results. debug_info: anyOf: - {} - type: 'null' title: Debug Info additionalProperties: false type: object required: - n_hits - search_request_id - displays title: SearchResponse SearchRequestV2: 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: anyOf: - type: string - type: 'null' title: Query description: The search query. additionalProperties: false type: object required: - market - tenant title: SearchRequestV2 SearchSuggestionsResponse: properties: suggestions_request_id: type: string title: Suggestions Request Id suggestions: items: anyOf: - $ref: '#/components/schemas/common__schema__search__QuerySuggestion' - $ref: '#/components/schemas/LegacyCategorySuggestion' type: array title: Suggestions description: List of suggestions for search queries that should be shown to the user while they are typing. additionalProperties: false type: object required: - suggestions_request_id - suggestions title: SearchSuggestionsResponse 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 BaseSearchRequestV2: properties: 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: anyOf: - type: string - type: 'null' title: Query description: The search query. additionalProperties: false type: object required: - market - tenant title: BaseSearchRequestV2 common__schema__search__QuerySuggestion: properties: type: const: query title: Type default: query title: type: string title: Title description: Title for suggestion. suggestions_result_id: type: string title: Suggestions Result Id additionalProperties: false type: object required: - title - suggestions_result_id title: QuerySuggestion LegacyCategorySuggestion: 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 type: const: category title: Type description: type default: category suggestions_result_id: type: string title: Suggestions Result Id additionalProperties: true type: object required: - category_id - title - suggestions_result_id title: LegacyCategorySuggestion 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 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 HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError SortingOrder: type: string enum: - asc - desc title: SortingOrder 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