Depict.AI Search (v2) API
The Search (v2) API from Depict.AI — 4 operation(s) for search (v2).
OpenAPI Specification
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<pre>\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 </pre>\n\n Example request body for applying a filter:\n <pre>\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 </pre>"
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<pre>\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</pre>"
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
</pre>'
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:
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
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
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
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
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
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
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
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
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
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
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
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
SortingOrder:
type: string
enum:
- asc
- desc
title: SortingOrder
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
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
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
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
ECategoryType:
type: string
enum:
- TAG
- CATEGORY
- TENANT_CATEGORY
- TENANT_SECONDARY_CATEGORY
- CAMPAIGN
- BRAND
title: ECategoryType
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
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
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
securitySchemes:
A
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/depictai/refs/heads/main/openapi/depictai-search-v2-api-openapi.yml