> ## Documentation Index > Fetch the complete documentation index at: https://docs.solya.app/llms.txt > Use this file to discover all available pages before exploring further. # Batch-resolve multiple entity hints in one call > Multi-entity single-shot resolver. Provide natural-language hints for brand, product, collection, and/or taxonomy types (color, size, sport, family, gender, category, style, design, shape) and receive a coordinated resolution in one round-trip. Key behaviors: (1) brand→product cross-constraint — when brand is resolved without ambiguity its id is used to scope the product search, eliminating BRAND_MISMATCH errors; (2) explicit disambiguation — when multiple plausible candidates exist the field carries ambiguous:true and resolved is absent; the agent must present candidates to the user; (3) inventory-item pivot — when product + color/size are resolved, the endpoint attempts to resolve the exact inventory item (variant×size) and returns inventoryItemId/variantId/sizeId coordinates; (4) flat coordinate IDs in the response (brandId, productId, …) are safe to pass directly to downstream filter APIs. ## OpenAPI ````yaml /openapi.json post /api/resolve openapi: 3.0.3 info: contact: email: dev@solya.io name: Solya Team description: >- # Solya API Solya is a fashion retail inventory management platform for buyers and merchandisers. This API exposes all capabilities needed to manage the inventory lifecycle: catalog browsing, risk detection, plan creation (Restock / Markdown / Rebalance), analytics queries, and data-platform operations. ## Authentication Three authentication schemes are supported: | Scheme | Header | Use case | |---|---|---| | **BearerAuth** | `Authorization: Bearer ` | Human users via the Solya web app (NextAuth session) | | **InternalBearerAuth** | `Authorization: Bearer ` | Internal jobs and cron tasks (static token per service) | | **ServiceAccountToken** | `Authorization: Bearer solya_sa_*` | LLM agents and programmatic clients (opaque token created via Settings) | All endpoints except `GET /api/health` require one of the above. See [Agent authentication guide](/docs/api/AGENT_AUTH.md) for the Service Account token flow. ## Response format Every endpoint returns an `ActionResponse` envelope: **Success:** ```json { "success": true, "data": { ... } } ``` **Error:** ```json { "success": false, "errorCode": "PLAN_NOT_FOUND", "error": "Human-readable message" } ``` The `errorCode` is a stable machine-readable string (see common error codes below). The `error` field is for human display only and may change between versions. ## Pagination List endpoints accept `page` (1-indexed, default 1) and `pageSize` (default 20, max 100). Responses include a `total` field with the total number of matching records. ``` GET /api/shops?page=2&pageSize=50 → { "success": true, "data": { "data": [...], "total": 120, "page": 2, "pageSize": 50 } } ``` ## Common error codes | HTTP status | errorCode | Meaning | |---|---|---| | 401 | `UNAUTHORIZED` | Token missing, expired, or invalid | | 403 | `FORBIDDEN` | Token valid but lacks the required permission or scope | | 404 | `NOT_FOUND` | Requested resource does not exist | | 409 | `BUSINESS_RULE_VIOLATION` | Business rule blocked the operation (see response details) | | 422 | `VALIDATION_ERROR` | Input failed Zod schema validation | | 429 | `RATE_LIMIT_EXCEEDED` | Rate limit hit (100 req/min per token) | | 500 | `INTERNAL_ERROR` | Unexpected server error | ## Rate limiting Default limit: **100 requests per minute** per authentication token. When the limit is exceeded the API returns HTTP 429 with `errorCode: "RATE_LIMIT_EXCEEDED"`. Agents should implement exponential back-off and respect the `Retry-After` header when present. ## Further reading See the [Agent guide](/docs/api/AGENT_GUIDE.md) for end-to-end workflows, call-chaining patterns, and anti-patterns to avoid. license: name: Proprietary url: https://solya.app/terms title: Solya API version: 1.0.0 x-ai-context: >- Solya is a fashion retail inventory management platform for retailers. Core concepts: - **Organization** (tenant): every endpoint is scoped by organizationId extracted from the token. - **Shop**: a physical point of sale belonging to the organization. - **ProductVariant**: a SKU — a product variant with size and color. - **Plan**: a Restock / Markdown / Rebalance grouping PlanItems to orchestrate inventory decisions. Typical agent workflow: 1. List the organization's shops — GET /api/shops 2. List variants at risk (stockout, overstock, slow-mover) — GET /api/inventory/risks 3. Create a plan — POST /api/restock-plans, /api/markdown-plans, or /api/rebalance-plans 4. Add items to the plan — POST /api/restock-plans/{planId}/items (or equivalent for other plan types) 5. Validate / submit the plan via the corresponding action endpoint Auth: use a Service Account token (see /docs/api/AGENT_AUTH.md). The token is created by an org admin via Settings and has the format solya_sa_<43 base64url chars>. All responses follow the ActionResponse envelope: - Success: { success: true, data: T } - Error: { success: false, errorCode: string, error: string } Use the errorCode field to drive retry logic or surface user-facing messages. servers: - description: Current environment url: https://app.solya.app security: - BearerAuth: [] tags: - description: >- Health and liveness endpoints. Use GET /api/health to verify the service is reachable before starting a workflow. No authentication required. name: System - description: >- Physical points of sale belonging to the organization. Supports listing, creation, update, and deactivation. Shops are referenced by all Plan types (Restock, Markdown, Rebalance) and by every inventory analytics endpoint. name: Shops - description: >- Product brands configured for the organization. Brands are used to filter catalog queries and analytics. Supports CRUD operations. name: Brands - description: >- The product catalog: style-level entities grouping one or more ProductVariants. Supports listing with rich filter options (brand, family, gender, season) and individual retrieval. name: Products - description: >- SKU-level product entities (a Product with a specific size and color). Variants are the atomic unit referenced by PlanItems, inventory risk alerts, and analytics queries. name: Variants - description: >- Curated product groupings used for seasonal assortment management. A Collection groups Variants and can be referenced when creating or filtering Plans. name: Collections - description: >- Current on-hand stock records per Variant per Shop. Used to understand the live inventory position before creating a restock or rebalance plan. name: Inventory Items - description: >- AI-detected inventory risk signals: stockout risk, overstock, slow-movers, and displaced stock. The primary input for agents building recommendation-driven plans. Supports filtering by shop, brand, risk type, and severity. name: Inventory Risks - description: >- AI-generated restock quantity recommendations per Variant per Shop. Consumed by agents to pre-populate Restock plan items. Based on sales velocity, stock coverage, and lead time. name: Recommendations - Restock - description: >- AI-generated markdown discount recommendations for slow-moving or overstock Variants. Consumed by agents to pre-populate Markdown plan items. Includes recommended discount rate and expected clearance timeline. name: Recommendations - Markdown - description: >- AI-generated stock transfer recommendations between shops to balance supply with demand. Consumed by agents to pre-populate Rebalance plan items. name: Recommendations - Rebalance - description: >- Historical sales transaction lines at the Variant + Shop + date level. Used by analytics and by the AI recommendation engine. Supports date-range and multi-dimensional filtering. name: Sales Lines - description: >- Purchase order lines tracking inbound stock from suppliers. Combined with stock and sales data to compute forward coverage and restock needs. name: Order Lines - description: >- Inventory movement records (transfers, returns, adjustments). Used to reconcile the stock ledger and audit stock changes between shops. name: Movement Lines - description: >- Running stock balance log per Variant per Shop. Provides a point-in-time view of stock levels and is the source of truth for coverage computations. name: Stock Ledger - description: >- Rebalance plans orchestrate stock transfers between shops. Supports creating plans, adding Variant items with proposed transfer quantities, reviewing, and submitting. Business rules are evaluated on item addition. name: Plans - Rebalance - description: >- Restock plans (order plans) orchestrate purchase orders to suppliers. Supports creating sessions, adding Variant items with proposed order quantities, reviewing totals, and submitting. Integrates with the order plan workflow. name: Plans - Restock - description: >- Autocomplete and typeahead search endpoints for catalog dimensions: products, brands, shops, sizes, families, genders, and more. Designed for fast UI search (low latency, small result sets). Use catalog list endpoints for full paginated access. name: Search - description: >- Manage file-based data ingestion: upload CSV/XLSX files, poll ingestion status, list historical ingestion runs, and trigger batch reprocessing. Used by the data team to import POS data and catalog updates. name: Data Platform - File Ingestions - description: >- Organization-level configuration for the data platform: data source connections, POS integration settings, and ingestion schedules. Requires elevated permissions. name: Data Platform - Settings - description: >- Configuration of automated inventory alerts: threshold-based rules that monitor stock levels, sales velocity, and coverage gaps. Supports CRUD for alert definitions; alert evaluation runs are triggered by the data platform scheduler. name: Data Platform - Alerts - description: >- Endpoints designed for LLM agents and programmatic clients. These endpoints expose agent-optimized response shapes. Authenticate with a Service Account token (format: solya_sa_*) created via Settings → API Tokens. name: Agent externalDocs: description: >- Complete guide for LLM agents and programmatic clients: authentication, pagination patterns, ActionResponse interpretation, call chaining, business rule error handling. url: /docs/api/AGENT_GUIDE.md paths: /api/resolve: post: tags: - Resolve summary: Batch-resolve multiple entity hints in one call description: >- Multi-entity single-shot resolver. Provide natural-language hints for brand, product, collection, and/or taxonomy types (color, size, sport, family, gender, category, style, design, shape) and receive a coordinated resolution in one round-trip. Key behaviors: (1) brand→product cross-constraint — when brand is resolved without ambiguity its id is used to scope the product search, eliminating BRAND_MISMATCH errors; (2) explicit disambiguation — when multiple plausible candidates exist the field carries ambiguous:true and resolved is absent; the agent must present candidates to the user; (3) inventory-item pivot — when product + color/size are resolved, the endpoint attempts to resolve the exact inventory item (variant×size) and returns inventoryItemId/variantId/sizeId coordinates; (4) flat coordinate IDs in the response (brandId, productId, …) are safe to pass directly to downstream filter APIs. operationId: resolveEntities requestBody: content: application/json: examples: brandAndProduct: summary: Resolve brand + product with cross-constraint value: brand: Nike product: Air Max 90 fullCoordinate: summary: Resolve to specific inventory item (product + color + size) value: brand: Nike color: Black product: Air Max 90 size: '40' taxonomyOnly: summary: Resolve taxonomy fields only (no entity hints) value: color: bleu turquoise size: M sport: running schema: additionalProperties: false description: >- Natural-language hints per entity type. Provide only fields you want resolved. properties: brand: description: Brand name or code hint, e.g. 'Nike', 'AD001'. minLength: 1 type: string category: description: >- Category hint resolved via taxonomy cascade, e.g. 'footwear'. minLength: 1 type: string collection: description: >- Collection name or code hint, e.g. 'Spring Summer 2025', 'SS25'. minLength: 1 type: string color: description: >- Color hint resolved via taxonomy cascade, e.g. 'bleu turquoise'. minLength: 1 type: string design: description: >- Design hint resolved via taxonomy cascade, e.g. 'monochrome'. minLength: 1 type: string family: description: >- Family hint resolved via taxonomy cascade, e.g. 'chaussures'. minLength: 1 type: string gender: description: >- Gender hint resolved via taxonomy cascade, e.g. 'homme', 'women'. minLength: 1 type: string product: description: >- Product name or code hint, e.g. 'Air Max 90'. Cross-constrained with resolved brand — only products of that brand are returned. minLength: 1 type: string shape: description: Shape hint resolved via taxonomy cascade, e.g. 'low top'. minLength: 1 type: string size: description: >- Size hint resolved via taxonomy cascade, e.g. '40', 'L', 'XL'. minLength: 1 type: string sport: description: >- Sport hint resolved via taxonomy cascade, e.g. 'running', 'football'. minLength: 1 type: string style: description: Style hint resolved via taxonomy cascade, e.g. 'casual'. minLength: 1 type: string type: object required: true responses: '200': content: application/json: examples: ambiguousProduct: summary: Brand resolved, product ambiguous (two fuzzy matches) value: data: brand: ambiguous: false candidates: - id: brand-uuid-nike label: Nike matchSource: exact score: 1 resolved: id: brand-uuid-nike label: Nike matchSource: exact score: 1 brandId: brand-uuid-nike product: ambiguous: true candidates: - brandId: brand-uuid-nike id: product-uuid-am90 label: Air Max 90 matchSource: fuzzy score: 0.68 - brandId: brand-uuid-nike id: product-uuid-am95 label: Air Max 95 matchSource: fuzzy score: 0.65 success: true brandAndProduct: summary: Brand + product resolved, product scoped to brand value: data: brand: ambiguous: false candidates: - id: brand-uuid-nike label: Nike matchSource: exact score: 1 resolved: id: brand-uuid-nike label: Nike matchSource: exact score: 1 brandId: brand-uuid-nike product: ambiguous: false candidates: - brandId: brand-uuid-nike id: product-uuid-am90 label: Air Max 90 matchSource: exact score: 1 resolved: brandId: brand-uuid-nike id: product-uuid-am90 label: Air Max 90 matchSource: exact score: 1 productId: product-uuid-am90 success: true fullCoordinate: summary: >- Inventory item resolved — returns inventoryItemId, variantId, sizeId value: data: brand: ambiguous: false candidates: - id: brand-uuid-nike label: Nike matchSource: exact score: 1 resolved: id: brand-uuid-nike label: Nike matchSource: exact score: 1 brandId: brand-uuid-nike color: ambiguous: false candidates: - fullPath: Color/Black id: color-uuid-black label: Black score: 1 resolved: fullPath: Color/Black id: color-uuid-black label: Black score: 1 colorId: color-uuid-black inventoryItemId: 550e8400-e29b-41d4-a716-446655440001 product: ambiguous: false candidates: - brandId: brand-uuid-nike id: product-uuid-am90 label: Air Max 90 matchSource: exact score: 1 resolved: brandId: brand-uuid-nike id: product-uuid-am90 label: Air Max 90 matchSource: exact score: 1 productId: product-uuid-am90 size: ambiguous: false candidates: - fullPath: Size/40 id: size-uuid-40 label: '40' score: 1 resolved: fullPath: Size/40 id: size-uuid-40 label: '40' score: 1 sizeId: 550e8400-e29b-41d4-a716-446655440003 variantId: 550e8400-e29b-41d4-a716-446655440002 success: true schema: description: >- ActionResponse envelope wrapping the multi-entity resolution result. properties: data: additionalProperties: false properties: brand: additionalProperties: false description: Brand resolution result. properties: ambiguous: description: >- True when multiple candidates exist and the top score is below 1.0 (not exact). Present `candidates` to the user rather than proceeding blindly. type: boolean candidates: description: >- All candidates ordered by score desc. May be empty. items: additionalProperties: false properties: brandId: description: >- Brand FK (product results only). Null = product has no brand. nullable: true type: string id: description: >- Stable entity id — use directly as a filter or FK value. type: string label: description: Display name of the entity. type: string matchSource: description: 'Cascade layer: exact | identifier | fuzzy' enum: - exact - identifier - fuzzy type: string score: description: >- Confidence score: 1.0=exact, 0.95=identifier, ≤0.75=fuzzy. maximum: 1 minimum: 0 type: number required: - id - label - score - matchSource type: object type: array resolved: additionalProperties: false description: >- Best candidate. Absent when ambiguous (multiple plausible matches) or no matches found. properties: brandId: description: >- Brand FK (product results only). Null = product has no brand. nullable: true type: string id: description: >- Stable entity id — use directly as a filter or FK value. type: string label: description: Display name of the entity. type: string matchSource: description: 'Cascade layer: exact | identifier | fuzzy' enum: - exact - identifier - fuzzy type: string score: description: >- Confidence score: 1.0=exact, 0.95=identifier, ≤0.75=fuzzy. maximum: 1 minimum: 0 type: number required: - id - label - score - matchSource type: object required: - candidates - ambiguous type: object brandId: description: >- Resolved brand UUID; set when brand resolved without ambiguity. type: string category: additionalProperties: false description: Category taxonomy resolution. properties: ambiguous: description: >- True when multiple candidates exist with a non-exact top score. type: boolean candidates: description: All candidates ordered by score desc. items: additionalProperties: false properties: fullPath: description: >- Slash-joined taxonomy path, e.g. 'Color/Blue/Turquoise'. type: string id: description: >- Stable taxonomy node id — use directly as a filter value. type: string label: description: Deepest level label, e.g. 'Turquoise'. type: string score: description: >- Confidence score: 1.0=exact, 0.95=alias, ≤0.75=ilike. maximum: 1 minimum: 0 type: number required: - id - label - score - fullPath type: object type: array resolved: additionalProperties: false description: >- Best candidate. Absent when ambiguous or no matches. properties: fullPath: description: >- Slash-joined taxonomy path, e.g. 'Color/Blue/Turquoise'. type: string id: description: >- Stable taxonomy node id — use directly as a filter value. type: string label: description: Deepest level label, e.g. 'Turquoise'. type: string score: description: >- Confidence score: 1.0=exact, 0.95=alias, ≤0.75=ilike. maximum: 1 minimum: 0 type: number required: - id - label - score - fullPath type: object required: - candidates - ambiguous type: object collection: additionalProperties: false description: Collection resolution result. properties: ambiguous: description: >- True when multiple candidates exist and the top score is below 1.0 (not exact). Present `candidates` to the user rather than proceeding blindly. type: boolean candidates: description: >- All candidates ordered by score desc. May be empty. items: additionalProperties: false properties: brandId: description: >- Brand FK (product results only). Null = product has no brand. nullable: true type: string id: description: >- Stable entity id — use directly as a filter or FK value. type: string label: description: Display name of the entity. type: string matchSource: description: 'Cascade layer: exact | identifier | fuzzy' enum: - exact - identifier - fuzzy type: string score: description: >- Confidence score: 1.0=exact, 0.95=identifier, ≤0.75=fuzzy. maximum: 1 minimum: 0 type: number required: - id - label - score - matchSource type: object type: array resolved: additionalProperties: false description: >- Best candidate. Absent when ambiguous (multiple plausible matches) or no matches found. properties: brandId: description: >- Brand FK (product results only). Null = product has no brand. nullable: true type: string id: description: >- Stable entity id — use directly as a filter or FK value. type: string label: description: Display name of the entity. type: string matchSource: description: 'Cascade layer: exact | identifier | fuzzy' enum: - exact - identifier - fuzzy type: string score: description: >- Confidence score: 1.0=exact, 0.95=identifier, ≤0.75=fuzzy. maximum: 1 minimum: 0 type: number required: - id - label - score - matchSource type: object required: - candidates - ambiguous type: object collectionId: description: Resolved collection UUID. type: string color: additionalProperties: false description: Color taxonomy resolution. properties: ambiguous: description: >- True when multiple candidates exist with a non-exact top score. type: boolean candidates: description: All candidates ordered by score desc. items: additionalProperties: false properties: fullPath: description: >- Slash-joined taxonomy path, e.g. 'Color/Blue/Turquoise'. type: string id: description: >- Stable taxonomy node id — use directly as a filter value. type: string label: description: Deepest level label, e.g. 'Turquoise'. type: string score: description: >- Confidence score: 1.0=exact, 0.95=alias, ≤0.75=ilike. maximum: 1 minimum: 0 type: number required: - id - label - score - fullPath type: object type: array resolved: additionalProperties: false description: >- Best candidate. Absent when ambiguous or no matches. properties: fullPath: description: >- Slash-joined taxonomy path, e.g. 'Color/Blue/Turquoise'. type: string id: description: >- Stable taxonomy node id — use directly as a filter value. type: string label: description: Deepest level label, e.g. 'Turquoise'. type: string score: description: >- Confidence score: 1.0=exact, 0.95=alias, ≤0.75=ilike. maximum: 1 minimum: 0 type: number required: - id - label - score - fullPath type: object required: - candidates - ambiguous type: object colorId: description: Resolved color taxonomy node id. type: string design: additionalProperties: false description: Design taxonomy resolution. properties: ambiguous: description: >- True when multiple candidates exist with a non-exact top score. type: boolean candidates: description: All candidates ordered by score desc. items: additionalProperties: false properties: fullPath: description: >- Slash-joined taxonomy path, e.g. 'Color/Blue/Turquoise'. type: string id: description: >- Stable taxonomy node id — use directly as a filter value. type: string label: description: Deepest level label, e.g. 'Turquoise'. type: string score: description: >- Confidence score: 1.0=exact, 0.95=alias, ≤0.75=ilike. maximum: 1 minimum: 0 type: number required: - id - label - score - fullPath type: object type: array resolved: additionalProperties: false description: >- Best candidate. Absent when ambiguous or no matches. properties: fullPath: description: >- Slash-joined taxonomy path, e.g. 'Color/Blue/Turquoise'. type: string id: description: >- Stable taxonomy node id — use directly as a filter value. type: string label: description: Deepest level label, e.g. 'Turquoise'. type: string score: description: >- Confidence score: 1.0=exact, 0.95=alias, ≤0.75=ilike. maximum: 1 minimum: 0 type: number required: - id - label - score - fullPath type: object required: - candidates - ambiguous type: object family: additionalProperties: false description: Family taxonomy resolution. properties: ambiguous: description: >- True when multiple candidates exist with a non-exact top score. type: boolean candidates: description: All candidates ordered by score desc. items: additionalProperties: false properties: fullPath: description: >- Slash-joined taxonomy path, e.g. 'Color/Blue/Turquoise'. type: string id: description: >- Stable taxonomy node id — use directly as a filter value. type: string label: description: Deepest level label, e.g. 'Turquoise'. type: string score: description: >- Confidence score: 1.0=exact, 0.95=alias, ≤0.75=ilike. maximum: 1 minimum: 0 type: number required: - id - label - score - fullPath type: object type: array resolved: additionalProperties: false description: >- Best candidate. Absent when ambiguous or no matches. properties: fullPath: description: >- Slash-joined taxonomy path, e.g. 'Color/Blue/Turquoise'. type: string id: description: >- Stable taxonomy node id — use directly as a filter value. type: string label: description: Deepest level label, e.g. 'Turquoise'. type: string score: description: >- Confidence score: 1.0=exact, 0.95=alias, ≤0.75=ilike. maximum: 1 minimum: 0 type: number required: - id - label - score - fullPath type: object required: - candidates - ambiguous type: object gender: additionalProperties: false description: Gender taxonomy resolution. properties: ambiguous: description: >- True when multiple candidates exist with a non-exact top score. type: boolean candidates: description: All candidates ordered by score desc. items: additionalProperties: false properties: fullPath: description: >- Slash-joined taxonomy path, e.g. 'Color/Blue/Turquoise'. type: string id: description: >- Stable taxonomy node id — use directly as a filter value. type: string label: description: Deepest level label, e.g. 'Turquoise'. type: string score: description: >- Confidence score: 1.0=exact, 0.95=alias, ≤0.75=ilike. maximum: 1 minimum: 0 type: number required: - id - label - score - fullPath type: object type: array resolved: additionalProperties: false description: >- Best candidate. Absent when ambiguous or no matches. properties: fullPath: description: >- Slash-joined taxonomy path, e.g. 'Color/Blue/Turquoise'. type: string id: description: >- Stable taxonomy node id — use directly as a filter value. type: string label: description: Deepest level label, e.g. 'Turquoise'. type: string score: description: >- Confidence score: 1.0=exact, 0.95=alias, ≤0.75=ilike. maximum: 1 minimum: 0 type: number required: - id - label - score - fullPath type: object required: - candidates - ambiguous type: object inventoryItemId: description: >- Resolved inventory-item id; set when product + color/size hints resolved to a unique item (variant × size). type: string product: additionalProperties: false description: >- Product resolution result. Scoped to resolved brand when available. properties: ambiguous: description: >- True when multiple candidates exist and the top score is below 1.0 (not exact). Present `candidates` to the user rather than proceeding blindly. type: boolean candidates: description: >- All candidates ordered by score desc. May be empty. items: additionalProperties: false properties: brandId: description: >- Brand FK (product results only). Null = product has no brand. nullable: true type: string id: description: >- Stable entity id — use directly as a filter or FK value. type: string label: description: Display name of the entity. type: string matchSource: description: 'Cascade layer: exact | identifier | fuzzy' enum: - exact - identifier - fuzzy type: string score: description: >- Confidence score: 1.0=exact, 0.95=identifier, ≤0.75=fuzzy. maximum: 1 minimum: 0 type: number required: - id - label - score - matchSource type: object type: array resolved: additionalProperties: false description: >- Best candidate. Absent when ambiguous (multiple plausible matches) or no matches found. properties: brandId: description: >- Brand FK (product results only). Null = product has no brand. nullable: true type: string id: description: >- Stable entity id — use directly as a filter or FK value. type: string label: description: Display name of the entity. type: string matchSource: description: 'Cascade layer: exact | identifier | fuzzy' enum: - exact - identifier - fuzzy type: string score: description: >- Confidence score: 1.0=exact, 0.95=identifier, ≤0.75=fuzzy. maximum: 1 minimum: 0 type: number required: - id - label - score - matchSource type: object required: - candidates - ambiguous type: object productId: description: >- Resolved product UUID; set when product resolved without ambiguity. type: string shape: additionalProperties: false description: Shape taxonomy resolution. properties: ambiguous: description: >- True when multiple candidates exist with a non-exact top score. type: boolean candidates: description: All candidates ordered by score desc. items: additionalProperties: false properties: fullPath: description: >- Slash-joined taxonomy path, e.g. 'Color/Blue/Turquoise'. type: string id: description: >- Stable taxonomy node id — use directly as a filter value. type: string label: description: Deepest level label, e.g. 'Turquoise'. type: string score: description: >- Confidence score: 1.0=exact, 0.95=alias, ≤0.75=ilike. maximum: 1 minimum: 0 type: number required: - id - label - score - fullPath type: object type: array resolved: additionalProperties: false description: >- Best candidate. Absent when ambiguous or no matches. properties: fullPath: description: >- Slash-joined taxonomy path, e.g. 'Color/Blue/Turquoise'. type: string id: description: >- Stable taxonomy node id — use directly as a filter value. type: string label: description: Deepest level label, e.g. 'Turquoise'. type: string score: description: >- Confidence score: 1.0=exact, 0.95=alias, ≤0.75=ilike. maximum: 1 minimum: 0 type: number required: - id - label - score - fullPath type: object required: - candidates - ambiguous type: object size: additionalProperties: false description: Size taxonomy resolution. properties: ambiguous: description: >- True when multiple candidates exist with a non-exact top score. type: boolean candidates: description: All candidates ordered by score desc. items: additionalProperties: false properties: fullPath: description: >- Slash-joined taxonomy path, e.g. 'Color/Blue/Turquoise'. type: string id: description: >- Stable taxonomy node id — use directly as a filter value. type: string label: description: Deepest level label, e.g. 'Turquoise'. type: string score: description: >- Confidence score: 1.0=exact, 0.95=alias, ≤0.75=ilike. maximum: 1 minimum: 0 type: number required: - id - label - score - fullPath type: object type: array resolved: additionalProperties: false description: >- Best candidate. Absent when ambiguous or no matches. properties: fullPath: description: >- Slash-joined taxonomy path, e.g. 'Color/Blue/Turquoise'. type: string id: description: >- Stable taxonomy node id — use directly as a filter value. type: string label: description: Deepest level label, e.g. 'Turquoise'. type: string score: description: >- Confidence score: 1.0=exact, 0.95=alias, ≤0.75=ilike. maximum: 1 minimum: 0 type: number required: - id - label - score - fullPath type: object required: - candidates - ambiguous type: object sizeId: description: >- Resolved size id. Sourced from inventory_item.taxonomy_size_id when inventory-item resolution succeeded, otherwise from the size taxonomy node. type: string sport: additionalProperties: false description: Sport taxonomy resolution. properties: ambiguous: description: >- True when multiple candidates exist with a non-exact top score. type: boolean candidates: description: All candidates ordered by score desc. items: additionalProperties: false properties: fullPath: description: >- Slash-joined taxonomy path, e.g. 'Color/Blue/Turquoise'. type: string id: description: >- Stable taxonomy node id — use directly as a filter value. type: string label: description: Deepest level label, e.g. 'Turquoise'. type: string score: description: >- Confidence score: 1.0=exact, 0.95=alias, ≤0.75=ilike. maximum: 1 minimum: 0 type: number required: - id - label - score - fullPath type: object type: array resolved: additionalProperties: false description: >- Best candidate. Absent when ambiguous or no matches. properties: fullPath: description: >- Slash-joined taxonomy path, e.g. 'Color/Blue/Turquoise'. type: string id: description: >- Stable taxonomy node id — use directly as a filter value. type: string label: description: Deepest level label, e.g. 'Turquoise'. type: string score: description: >- Confidence score: 1.0=exact, 0.95=alias, ≤0.75=ilike. maximum: 1 minimum: 0 type: number required: - id - label - score - fullPath type: object required: - candidates - ambiguous type: object style: additionalProperties: false description: Style taxonomy resolution. properties: ambiguous: description: >- True when multiple candidates exist with a non-exact top score. type: boolean candidates: description: All candidates ordered by score desc. items: additionalProperties: false properties: fullPath: description: >- Slash-joined taxonomy path, e.g. 'Color/Blue/Turquoise'. type: string id: description: >- Stable taxonomy node id — use directly as a filter value. type: string label: description: Deepest level label, e.g. 'Turquoise'. type: string score: description: >- Confidence score: 1.0=exact, 0.95=alias, ≤0.75=ilike. maximum: 1 minimum: 0 type: number required: - id - label - score - fullPath type: object type: array resolved: additionalProperties: false description: >- Best candidate. Absent when ambiguous or no matches. properties: fullPath: description: >- Slash-joined taxonomy path, e.g. 'Color/Blue/Turquoise'. type: string id: description: >- Stable taxonomy node id — use directly as a filter value. type: string label: description: Deepest level label, e.g. 'Turquoise'. type: string score: description: >- Confidence score: 1.0=exact, 0.95=alias, ≤0.75=ilike. maximum: 1 minimum: 0 type: number required: - id - label - score - fullPath type: object required: - candidates - ambiguous type: object variantId: description: >- Resolved variant id sourced from the matched inventory item (color dimension of product). type: string type: object success: enum: - true type: boolean required: - success - data type: object description: Successful resolution '400': description: Validation error (invalid body) '401': description: Unauthorized '500': description: Internal server error security: - BearerAuth: [] components: securitySchemes: BearerAuth: bearerFormat: JWT description: >- User session token issued by NextAuth. For human users accessing Solya via the web application. scheme: bearer type: http ````