Search product variants

curl --request GET \
  --url https://app.solya.app/api/search/product-variants \
  --header 'Authorization: Bearer <token>'

[
  {
    "barcode": "1234567890001",
    "collectionId": "collection-uuid-fw25",
    "externalReference": "EXT-001",
    "id": "variant-uuid-1",
    "name": "Air Max 90 / Black",
    "productId": "product-uuid-1",
    "sku": "AM90-BLK-42"
  },
  {
    "barcode": null,
    "collectionId": "collection-uuid-fw25",
    "externalReference": null,
    "id": "variant-uuid-2",
    "name": "Air Max 90 / White",
    "productId": "product-uuid-1",
    "sku": "AM90-WHT-42"
  }
]

Search product variants

Autocomplete search for product variants by name, SKU, external reference, or barcode. Identifier fields (sku, externalReference, barcode) use exact/prefix matching so that a scan of ‘SKU-123’ does not fuzzy-match noise; full_name uses substring matching. Exact identifier hits rank above prefix hits, which rank above name matches. Optionally scope to a known product with productId. Returns productId and collectionId so agents can pivot variant → product or collection without a second call. Size is not returned — size lives on inventory_items, not variants.

GET

api

product-variants

curl --request GET \
  --url https://app.solya.app/api/search/product-variants \
  --header 'Authorization: Bearer <token>'

[
  {
    "barcode": "1234567890001",
    "collectionId": "collection-uuid-fw25",
    "externalReference": "EXT-001",
    "id": "variant-uuid-1",
    "name": "Air Max 90 / Black",
    "productId": "product-uuid-1",
    "sku": "AM90-BLK-42"
  },
  {
    "barcode": null,
    "collectionId": "collection-uuid-fw25",
    "externalReference": null,
    "id": "variant-uuid-2",
    "name": "Air Max 90 / White",
    "productId": "product-uuid-1",
    "sku": "AM90-WHT-42"
  }
]

Authorizations

Authorization

string

header

required

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

Query Parameters

string

Canonical text-filter param (preferred). Partial text to filter results by name (case-insensitive prefix/substring match). Use q instead of the deprecated search alias — q matches the param name advertised in MCP tool examples and used on /api/products.

string

Deprecated: use q instead. Backwards-compatible alias — when both q and search are supplied, q takes precedence.

limit

number

default:10

Maximum number of results to return (1–100)

Required range: 1 <= x <= 100

ids

string

Comma-separated list of IDs to resolve by exact match

productId

string

Filter results to variants of this product UUID

Response

Successful response

data

object[]

required

Show child attributes

success

enum<boolean>

required

Available options:

true

Search product tags Search products