iRetail PRO
Русский Get a key
Menu

iRetail PRO store node 1.0.0-m1: search

8 operations

← All documentation · Source: contracts openapi/store-v1.yaml at 8000474.

← iRetail PRO store node 1.0.0-m1

Operations

GET /v1/search/items Search the catalog by meaning, exact matches first (spec/SEARCH.md, Searching); the license module search.

operationId searchItems · Permission item.read

Parameters

Name In Type Description
IRetail-App header string Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
q required query string The query.
group_id query string (uuid) Only items in this group or below it.
tag_id query string (uuid) Only items carrying this tag.
store_id query string (uuid) The store whose price the items carry; a store node uses its own store when absent.
include_inactive query boolean Inactive items too.
limit query integer Items to answer, 1–50.

Responses

GET /v1/search/suggestions Tags and groups the node suggests for items, newest first (spec/SEARCH.md, Suggestions).

operationId listSuggestions · Permission item.read

Parameters

Name In Type Description
IRetail-App header string Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
status query "open" | "accepted" | "dismissed" Open by default.
kind query "tag" | "group"
item_id query string (uuid) One item's suggestions.
limit query integer Page size, 1–200.
after query string Cursor from the previous page.

Responses

POST /v1/search/suggestions/{id}/accept Give the item the tag or the group, as an edit of the item by the caller.

operationId acceptSuggestion · Permission item.edit

Parameters

Name In Type Description
IRetail-App header string Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
id required path string (uuid) Id.

Responses

POST /v1/search/suggestions/{id}/dismiss Do not suggest it again for the item.

operationId dismissSuggestion · Permission item.edit

Parameters

Name In Type Description
IRetail-App header string Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
id required path string (uuid) Id.

Responses

GET /v1/search/settings The embedding provider and the suggestions' settings (spec/SEARCH.md); never the key.

operationId getSearchSettings · Permission search.manage

Parameters

Name In Type Description
IRetail-App header string Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).

Responses

PUT /v1/search/settings Set search up; a change of the model starts a new index.

operationId putSearchSettings · Permission search.manage

Parameters

Name In Type Description
IRetail-App header string Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
If-Match header string The version the change is based on.

Request body required

Responses

GET /v1/search/index The active index and the one building, with their progress.

operationId getSearchIndex · Permission item.read

Parameters

Name In Type Description
IRetail-App header string Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).

Responses

POST /v1/search/index/rebuild Start a new index with the settings' model; the active one answers until it is ready.

operationId rebuildSearchIndex · Permission search.manage

Parameters

Name In Type Description
IRetail-App header string Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).

Responses

Schemas

Error object

Every error response.

error required string Stable code, see spec/API.md.
message required string English text for logs.
details object

LocalizedText map of string

Text by language code; the organization's default language must be present.

Barcode object

A barcode of the item or of a pack of it.

barcode required string
pack_quantity_milli required integer (int64)

StorePrice object

price_minor required integer (int64)
currency required string

ModifierOption object

id required string
name required LocalizedText
price_delta_minor required integer (int64) Added to the item's price; may be negative.

ModifierGroup object

id required string
name required LocalizedText
min required integer
max required integer
options required array of ModifierOption

Item object

id required string (uuid)
sku required string
plu required string | null
name required LocalizedText
kind required "piece" | "weighed" | "variable_weight" | "service" | "kit" | "gift_card" A kit takes its components' stock at the sale (spec/STOCK.md, Kits); a gift card line sells stored value (spec/LOYALTY.md, Gift cards).
base_unit required "each" | "kg" | "lb" | "l" | "us_gal" | "m" | "ft"
tax_codes required array of string
group_id required string (uuid) | null
profile required string | null
attributes required object Profile fields (JSON), validated by the profile's schema.
stock_policy required "fifo" | "fefo"
discountable required boolean
active required boolean
barcodes required array of Barcode
modifier_groups required array of ModifierGroup Options a line of the item takes (spec/FOOD_SERVICE.md).
tags required array of ItemTag The item's tags in the order of their ids (spec/SEARCH.md, Tags).
price required StorePrice | null
variant_options required array of VariantOption On a parent, its options in order (spec/VARIANTS.md); empty on every other item.
parent_id required string (uuid) | null On a variant, its parent (spec/VARIANTS.md); set when the item is made.
variant_values required map of string | null On a variant, a value code for each of the parent's option codes.
serial_tracked required boolean Each unit's serial is recorded at receiving, sale, return and write-off (spec/VARIANTS.md).
photo_id string (uuid) | null The item's photo (POST /v1/item-photos) for the storefront, or null; absent from a node before 1.1.
kit_components required array of Component A kit's components, 1 to 20 (spec/STOCK.md, Kits); empty on every other item. Each is taxed as the kit is (its tax_category and tax_codes) and carries no deposit, or the save is refused with kit_tax_mixed.
version required integer (int64)

VariantValue object

code required string
name required LocalizedText

VariantOption object

code required string
name required LocalizedText
values required array of VariantValue

ItemTag object

tag_id required string (uuid)
source required "manual" | "suggested"
confidence required integer | null The accepted suggestion's confidence; null when manual.

SearchHit object

item required Item
match required "exact" | "semantic"
available_milli required integer (int64) | null Available quantity on a store node (spec/STOCK.md); null at the hub.

SearchIndex object

id required string (uuid)
model required string bge-m3, or the endpoint's model with its host.
dimensions required integer
indexed required integer (int64)
total required integer (int64)
started_at required string (date-time)
ready_at required string (date-time) | null

SearchIndexStatus object

active required null | SearchIndex
building required null | SearchIndex

SearchResult object

items required array of SearchHit
index required SearchIndex

SearchProvider object

kind required "local" | "openai_compatible"
base_url string openai_compatible only, answered from IRETAIL_SEARCH_KEY_<NAME>_BASE_URL; a value written is ignored (spec/SEARCH.md, Settings).
model string openai_compatible only.
dimensions integer openai_compatible only.
max_input_tokens integer openai_compatible only.
key string openai_compatible only. The key's name, or none; the node reads IRETAIL_SEARCH_KEY_<NAME> (spec/SEARCH.md). Never the key.

SearchSuggestionSettings object

enabled required boolean
neighbors required integer
min_score required integer
min_confidence required integer

SearchSettingsPut object

provider required SearchProvider
suggestions required SearchSuggestionSettings

SearchSettings object

provider required SearchProvider
suggestions required SearchSuggestionSettings
key_present required boolean Whether the node holds the named key, or none is needed.
version required integer

SuggestionResolver object

id required string (uuid)
name required string

Suggestion object

A tag or a group the node suggests for an item (spec/SEARCH.md, Suggestions).

id required string (uuid)
item_id required string (uuid)
item_name required LocalizedText
kind required "tag" | "group"
target_id required string (uuid)
target_name required LocalizedText
confidence required integer
status required "open" | "accepted" | "dismissed"
created_at required string (date-time)
resolved_at required string (date-time) | null
resolved_by required null | SuggestionResolver

SuggestionPage object

items required array of Suggestion
next required string | null

Component object

A kit's or a recipe's component: how much of the item (spec/STOCK.md).

item_id required string (uuid)
quantity_milli required integer (int64)