curl --request POST \
  --url https://app.solya.app/api/resolve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "brand": "Nike",
  "product": "Air Max 90"
}
'

{
  "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
}

Resolve

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.

POST

/

api

/

resolve

curl --request POST \
  --url https://app.solya.app/api/resolve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "brand": "Nike",
  "product": "Air Max 90"
}
'

{
  "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
}

Authorizations

Authorization

string

header

required

User session token issued by NextAuth. For human users accessing Solya via the web application.

Body

application/json

Natural-language hints per entity type. Provide only fields you want resolved.

brand

string

Brand name or code hint, e.g. 'Nike', 'AD001'.

Minimum string length: 1

category

string

Category hint resolved via taxonomy cascade, e.g. 'footwear'.

Minimum string length: 1

collection

string

Collection name or code hint, e.g. 'Spring Summer 2025', 'SS25'.

Minimum string length: 1

color

string

Color hint resolved via taxonomy cascade, e.g. 'bleu turquoise'.

Minimum string length: 1

design

string

Design hint resolved via taxonomy cascade, e.g. 'monochrome'.

Minimum string length: 1

family

string

Family hint resolved via taxonomy cascade, e.g. 'chaussures'.

Minimum string length: 1

gender

string

Gender hint resolved via taxonomy cascade, e.g. 'homme', 'women'.

Minimum string length: 1

product

string

Product name or code hint, e.g. 'Air Max 90'. Cross-constrained with resolved brand — only products of that brand are returned.

Minimum string length: 1

shape

string

Shape hint resolved via taxonomy cascade, e.g. 'low top'.

Minimum string length: 1

size

string

Size hint resolved via taxonomy cascade, e.g. '40', 'L', 'XL'.

Minimum string length: 1

sport

string

Sport hint resolved via taxonomy cascade, e.g. 'running', 'football'.

Minimum string length: 1

style

string

Style hint resolved via taxonomy cascade, e.g. 'casual'.

Minimum string length: 1

Response

Successful resolution

ActionResponse envelope wrapping the multi-entity resolution result.

data

object

required

Show child attributes

success

enum<boolean>

required

Available options:

true